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

futimens.3p (10743B)


  1. '\" et
  2. .TH FUTIMENS "3P" 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. futimens, utimensat, utimes
  12. \(em set file access and modification times
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <sys/stat.h>
  17. .P
  18. int futimens(int \fIfd\fP, const struct timespec \fItimes\fP[2]);
  19. .P
  20. #include <fcntl.h>
  21. .P
  22. int utimensat(int \fIfd\fP, const char *\fIpath\fP, const struct timespec \fItimes\fP[2],
  23. int \fIflag\fP);
  24. .P
  25. #include <sys/time.h>
  26. .P
  27. int utimes(const char *\fIpath\fP, const struct timeval \fItimes\fP[2]);
  28. .fi
  29. .SH DESCRIPTION
  30. The
  31. \fIfutimens\fR()
  32. and
  33. \fIutimensat\fR()
  34. functions shall set the access and modification times of a file
  35. to the values of the
  36. .IR times
  37. argument. The
  38. \fIfutimens\fR()
  39. function changes the times of the file associated with the file
  40. descriptor
  41. .IR fd .
  42. The
  43. \fIutimensat\fR()
  44. function changes the times of the file pointed to by the
  45. .IR path
  46. argument, relative to the directory associated with the file
  47. descriptor
  48. .IR fd .
  49. Both functions allow time specifications accurate to the nanosecond.
  50. .P
  51. For
  52. \fIfutimens\fR()
  53. and
  54. \fIutimensat\fR(),
  55. the
  56. .IR times
  57. argument is an array of two
  58. .BR timespec
  59. structures. The first array member represents the date and time of
  60. last access, and the second member represents the date and time of last
  61. modification. The times in the
  62. .BR timespec
  63. structure are measured in seconds and nanoseconds since the Epoch. The
  64. file's relevant timestamp shall be set to the greatest value supported
  65. by the file system that is not greater than the specified time.
  66. .P
  67. If the
  68. .IR tv_nsec
  69. field of a
  70. .BR timespec
  71. structure has the special value UTIME_NOW, the file's relevant timestamp
  72. shall be set to the greatest value supported by the file system that is
  73. not greater than the current time. If the
  74. .IR tv_nsec
  75. field has the special value UTIME_OMIT, the file's relevant timestamp
  76. shall not be changed. In either case, the
  77. .IR tv_sec
  78. field shall be ignored.
  79. .P
  80. If the
  81. .IR times
  82. argument is a null pointer, both the access and modification timestamps
  83. shall be set to the greatest value supported by the file system that is
  84. not greater than the current time. If
  85. \fIutimensat\fR()
  86. is passed a relative path in the
  87. .IR path
  88. argument, the file to be used shall be relative to the directory
  89. associated with the file descriptor
  90. .IR fd
  91. instead of the current working directory. If the access mode of
  92. the open file description associated with the file descriptor is not
  93. O_SEARCH, the function shall check whether directory searches
  94. are permitted using the current permissions of the directory
  95. underlying the file descriptor. If the access mode is O_SEARCH,
  96. the function shall not perform the check.
  97. .P
  98. If
  99. \fIutimensat\fR()
  100. is passed the special value AT_FDCWD in the
  101. .IR fd
  102. parameter, the current working directory shall be used.
  103. .P
  104. Only a process with the effective user ID equal to the user ID of the
  105. file, or with write access to the file, or with appropriate privileges
  106. may use
  107. \fIfutimens\fR()
  108. or
  109. \fIutimensat\fR()
  110. with a null pointer as the
  111. .IR times
  112. argument or with both
  113. .IR tv_nsec
  114. fields set to the special value UTIME_NOW. Only a process with the
  115. effective user ID equal to the user ID of the file or with appropriate
  116. privileges may use
  117. \fIfutimens\fR()
  118. or
  119. \fIutimensat\fR()
  120. with a non-null
  121. .IR times
  122. argument that does not have both
  123. .IR tv_nsec
  124. fields set to UTIME_NOW and does not have both
  125. .IR tv_nsec
  126. fields set to UTIME_OMIT. If both
  127. .IR tv_nsec
  128. fields are set to UTIME_OMIT, no ownership or permissions check shall be
  129. performed for the file, but other error conditions may still be detected
  130. (including
  131. .BR [EACCES]
  132. errors related to the path prefix).
  133. .P
  134. Values for the
  135. .IR flag
  136. argument of
  137. \fIutimensat\fR()
  138. are constructed by a bitwise-inclusive OR of flags from the following
  139. list, defined in
  140. .IR <fcntl.h> :
  141. .IP AT_SYMLINK_NOFOLLOW 6
  142. .br
  143. If
  144. .IR path
  145. names a symbolic link, then the access and modification times
  146. of the symbolic link are changed.
  147. .br
  148. .P
  149. Upon successful completion,
  150. \fIfutimens\fR()
  151. and
  152. \fIutimensat\fR()
  153. shall mark the last file status change timestamp for update,
  154. with the exception that if both
  155. .IR tv_nsec
  156. fields are set to UTIME_OMIT, the file status change timestamp
  157. need not be marked for update.
  158. .P
  159. The
  160. \fIutimes\fR()
  161. function shall be equivalent to the
  162. \fIutimensat\fR()
  163. function with the special value AT_FDCWD as the
  164. .IR fd
  165. argument and the
  166. .IR flag
  167. argument set to zero, except that the
  168. .IR times
  169. argument is a
  170. .BR timeval
  171. structure rather than a
  172. .BR timespec
  173. structure, and accuracy is only to the microsecond, not nanosecond,
  174. and rounding towards the nearest second may occur.
  175. .SH "RETURN VALUE"
  176. Upon successful completion, these functions shall return 0.
  177. Otherwise, these functions shall return \-1 and set
  178. .IR errno
  179. to indicate the error. If \-1 is returned, the file times shall
  180. not be affected.
  181. .SH ERRORS
  182. These functions shall fail if:
  183. .TP
  184. .BR EACCES
  185. The
  186. .IR times
  187. argument is a null pointer, or both
  188. .IR tv_nsec
  189. values are UTIME_NOW, and the effective user ID of the process
  190. does not match the owner of the file and write access is denied.
  191. .TP
  192. .BR EINVAL
  193. Either of the
  194. .IR times
  195. argument structures specified a
  196. .IR tv_nsec
  197. value that was neither UTIME_NOW nor UTIME_OMIT, and was a value less
  198. than zero or greater than or equal to 1\|000 million.
  199. .TP
  200. .BR EINVAL
  201. A new file timestamp would be a value whose
  202. .IR tv_sec
  203. component is not a value supported by the file system.
  204. .TP
  205. .BR EPERM
  206. The
  207. .IR times
  208. argument is not a null pointer, does not have both
  209. .IR tv_nsec
  210. fields set to UTIME_NOW, does not have both
  211. .IR tv_nsec
  212. fields set to UTIME_OMIT, the calling process' effective user ID does
  213. not match the owner of the file, and the calling process does not have
  214. appropriate privileges.
  215. .TP
  216. .BR EROFS
  217. The file system containing the file is read-only.
  218. .P
  219. The
  220. \fIfutimens\fR()
  221. function shall fail if:
  222. .TP
  223. .BR EBADF
  224. The
  225. .IR fd
  226. argument is not a valid file descriptor.
  227. .P
  228. The
  229. \fIutimensat\fR()
  230. function shall fail if:
  231. .TP
  232. .BR EACCES
  233. The access mode of the open file description associated with
  234. .IR fd
  235. is not O_SEARCH and the permissions of the directory underlying
  236. .IR fd
  237. do not permit directory searches.
  238. .TP
  239. .BR EBADF
  240. The
  241. .IR path
  242. argument does not specify an absolute path and the
  243. .IR fd
  244. argument is neither AT_FDCWD nor a valid file descriptor open
  245. for reading or searching.
  246. .TP
  247. .BR ENOTDIR
  248. The
  249. .IR path
  250. argument is not an absolute path and
  251. .IR fd
  252. is a file descriptor associated with a non-directory file.
  253. .P
  254. The
  255. \fIutimensat\fR()
  256. and
  257. \fIutimes\fR()
  258. functions shall fail if:
  259. .TP
  260. .BR EACCES
  261. Search permission is denied by a component of the path prefix.
  262. .TP
  263. .BR ELOOP
  264. A loop exists in symbolic links encountered during resolution of the
  265. .IR path
  266. argument.
  267. .TP
  268. .BR ENAMETOOLONG
  269. .br
  270. The length of a component of a pathname is longer than
  271. {NAME_MAX}.
  272. .TP
  273. .BR ENOENT
  274. A component of
  275. .IR path
  276. does not name an existing file or
  277. .IR path
  278. is an empty string.
  279. .TP
  280. .BR ENOTDIR
  281. A component of the path prefix names an existing file that is neither
  282. a directory nor a symbolic link to a directory, or the
  283. .IR path
  284. argument contains at least one non-\c
  285. <slash>
  286. character and ends with one or more trailing
  287. <slash>
  288. characters and the last pathname component names an existing file
  289. that is neither a directory nor a symbolic link to a directory.
  290. .P
  291. The
  292. \fIutimensat\fR()
  293. and
  294. \fIutimes\fR()
  295. functions may fail if:
  296. .TP
  297. .BR ELOOP
  298. More than
  299. {SYMLOOP_MAX}
  300. symbolic links were encountered during resolution of the
  301. .IR path
  302. argument.
  303. .TP
  304. .BR ENAMETOOLONG
  305. .br
  306. The length of a pathname exceeds
  307. {PATH_MAX},
  308. or pathname resolution of a symbolic link produced an intermediate
  309. result with a length that exceeds
  310. {PATH_MAX}.
  311. .P
  312. The
  313. \fIutimensat\fR()
  314. function may fail if:
  315. .TP
  316. .BR EINVAL
  317. The value of the
  318. .IR flag
  319. argument is not valid.
  320. .LP
  321. .IR "The following sections are informative."
  322. .SH EXAMPLES
  323. None.
  324. .SH "APPLICATION USAGE"
  325. None.
  326. .SH RATIONALE
  327. The purpose of the
  328. \fIutimensat\fR()
  329. function is to set the access and modification time of files in
  330. directories other than the current working directory without exposure
  331. to race conditions. Any part of the path of a file could be changed in
  332. parallel to a call to
  333. \fIutimes\fR(),
  334. resulting in unspecified behavior. By opening a file descriptor for
  335. the target directory and using the
  336. \fIutimensat\fR()
  337. function it can be guaranteed that the changed file is located relative
  338. to the desired directory.
  339. .P
  340. The standard developers considered including a special case for the
  341. permissions required by
  342. \fIutimensat\fR()
  343. when one
  344. .IR tv_nsec
  345. field is UTIME_NOW and the other is UTIME_OMIT. One possibility would
  346. be to include this case in with the cases where
  347. .IR times
  348. is a null pointer or both fields are UTIME_NOW, where the call is allowed
  349. if the process has write permission for the file. However, associating
  350. write permission with an update to just the last data access timestamp
  351. (which is normally updated by
  352. \fIread\fR())
  353. did not seem appropriate. The other possibility would be to specify that
  354. this one case is allowed if the process has read permission, but this
  355. was felt to be too great a departure from the
  356. \fIutime\fR()
  357. and
  358. \fIutimes\fR()
  359. functions on which
  360. \fIutimensat\fR()
  361. is based. If an application needs to set the last data access timestamp
  362. to the current time for a file on which it has read permission but is not
  363. the owner, it can do so by opening the file, reading one or more bytes
  364. (or reading a directory entry, if the file is a directory), and then
  365. closing it.
  366. .SH "FUTURE DIRECTIONS"
  367. None.
  368. .SH "SEE ALSO"
  369. .IR "\fIread\fR\^(\|)",
  370. .IR "\fIutime\fR\^(\|)"
  371. .P
  372. The Base Definitions volume of POSIX.1\(hy2017,
  373. .IR "\fB<fcntl.h>\fP",
  374. .IR "\fB<sys_stat.h>\fP",
  375. .IR "\fB<sys_time.h>\fP"
  376. .\"
  377. .SH COPYRIGHT
  378. Portions of this text are reprinted and reproduced in electronic form
  379. from IEEE Std 1003.1-2017, Standard for Information Technology
  380. -- Portable Operating System Interface (POSIX), The Open Group Base
  381. Specifications Issue 7, 2018 Edition,
  382. Copyright (C) 2018 by the Institute of
  383. Electrical and Electronics Engineers, Inc and The Open Group.
  384. In the event of any discrepancy between this version and the original IEEE and
  385. The Open Group Standard, the original IEEE and The Open Group Standard
  386. is the referee document. The original Standard can be obtained online at
  387. http://www.opengroup.org/unix/online.html .
  388. .PP
  389. Any typographical or formatting errors that appear
  390. in this page are most likely
  391. to have been introduced during the conversion of the source files to
  392. man page format. To report such errors, see
  393. https://www.kernel.org/doc/man-pages/reporting_bugs.html .