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

utime.3p (5433B)


  1. '\" et
  2. .TH UTIME "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. utime
  12. \(em set file access and modification times
  13. .SH SYNOPSIS
  14. .LP
  15. .nf
  16. #include <utime.h>
  17. .P
  18. int utime(const char *\fIpath\fP, const struct utimbuf *\fItimes\fP);
  19. .fi
  20. .SH DESCRIPTION
  21. The
  22. \fIutime\fR()
  23. function shall set the access and modification times of the file named
  24. by the
  25. .IR path
  26. argument.
  27. .P
  28. If
  29. .IR times
  30. is a null pointer, the access and modification times of the file shall
  31. be set to the current time. The effective user ID of the process shall
  32. match the owner of the file, or the process has write permission to the
  33. file or has appropriate privileges, to use
  34. \fIutime\fR()
  35. in this manner.
  36. .P
  37. If
  38. .IR times
  39. is not a null pointer,
  40. .IR times
  41. shall be interpreted as a pointer to a
  42. .BR utimbuf
  43. structure and the access and modification times shall be set to the
  44. values contained in the designated structure. Only a process with
  45. the effective user ID equal to the user ID of the file or a process with
  46. appropriate privileges may use
  47. \fIutime\fR()
  48. this way.
  49. .P
  50. The
  51. .BR utimbuf
  52. structure is defined in the
  53. .IR <utime.h>
  54. header. The times in the structure
  55. .BR utimbuf
  56. are measured in seconds since the Epoch.
  57. .P
  58. Upon successful completion, the
  59. \fIutime\fR()
  60. function shall mark the last file status change timestamp
  61. for update; see
  62. .IR <sys/stat.h> .
  63. .SH "RETURN VALUE"
  64. Upon successful completion, 0 shall be returned. Otherwise, \-1
  65. shall be returned and
  66. .IR errno
  67. shall be set to indicate the error, and the file times shall not be
  68. affected.
  69. .SH ERRORS
  70. The
  71. \fIutime\fR()
  72. function shall fail if:
  73. .TP
  74. .BR EACCES
  75. Search permission is denied by a component of the path prefix; or the
  76. .IR times
  77. argument is a null pointer and the effective user ID of the process
  78. does not match the owner of the file, the process does not have write
  79. permission for the file, and the process does not have appropriate
  80. privileges.
  81. .TP
  82. .BR ELOOP
  83. A loop exists in symbolic links encountered during resolution of the
  84. .IR path
  85. argument.
  86. .TP
  87. .BR ENAMETOOLONG
  88. .br
  89. The length of a component of a pathname is longer than
  90. {NAME_MAX}.
  91. .TP
  92. .BR ENOENT
  93. A component of
  94. .IR path
  95. does not name an existing file or
  96. .IR path
  97. is an empty string.
  98. .TP
  99. .BR ENOTDIR
  100. A component of the path prefix names an existing file that is neither
  101. a directory nor a symbolic link to a directory, or the
  102. .IR path
  103. argument contains at least one non-\c
  104. <slash>
  105. character and ends with one or more trailing
  106. <slash>
  107. characters and the last pathname component names an existing file
  108. that is neither a directory nor a symbolic link to a directory.
  109. .TP
  110. .BR EPERM
  111. The
  112. .IR times
  113. argument is not a null pointer and the effective user ID of the calling
  114. process does not match the owner of the file and the calling process
  115. does not have appropriate privileges.
  116. .TP
  117. .BR EROFS
  118. The file system containing the file is read-only.
  119. .br
  120. .P
  121. The
  122. \fIutime\fR()
  123. function may fail if:
  124. .TP
  125. .BR ELOOP
  126. More than
  127. {SYMLOOP_MAX}
  128. symbolic links were encountered during resolution of the
  129. .IR path
  130. argument.
  131. .TP
  132. .BR ENAMETOOLONG
  133. .br
  134. The length of a pathname exceeds
  135. {PATH_MAX},
  136. or pathname resolution of a symbolic link produced an intermediate
  137. result with a length that exceeds
  138. {PATH_MAX}.
  139. .LP
  140. .IR "The following sections are informative."
  141. .SH EXAMPLES
  142. None.
  143. .SH "APPLICATION USAGE"
  144. Since the
  145. .BR utimbuf
  146. structure only contains
  147. .BR time_t
  148. variables and is not accurate to fractions of a second,
  149. applications should use the
  150. \fIutimensat\fR()
  151. function instead of the obsolescent
  152. \fIutime\fR()
  153. function.
  154. .SH RATIONALE
  155. The
  156. .IR actime
  157. structure member must be present so that an application may set it,
  158. even though an implementation may ignore it and not change the last data
  159. access timestamp on the file. If an application intends to leave one of
  160. the times of a file unchanged while changing the other, it should use
  161. \fIstat\fR()
  162. or
  163. \fIfstat\fR()
  164. to retrieve the file's
  165. .IR st_atim
  166. and
  167. .IR st_mtim
  168. parameters, set
  169. .IR actime
  170. and
  171. .IR modtime
  172. in the buffer, and change one of them before making the
  173. \fIutime\fR()
  174. call.
  175. .SH "FUTURE DIRECTIONS"
  176. The
  177. \fIutime\fR()
  178. function may be removed in a future version.
  179. .SH "SEE ALSO"
  180. .IR "\fIfstat\fR\^(\|)",
  181. .IR "\fIfstatat\fR\^(\|)",
  182. .IR "\fIfutimens\fR\^(\|)"
  183. .P
  184. The Base Definitions volume of POSIX.1\(hy2017,
  185. .IR "\fB<sys_stat.h>\fP",
  186. .IR "\fB<utime.h>\fP"
  187. .\"
  188. .SH COPYRIGHT
  189. Portions of this text are reprinted and reproduced in electronic form
  190. from IEEE Std 1003.1-2017, Standard for Information Technology
  191. -- Portable Operating System Interface (POSIX), The Open Group Base
  192. Specifications Issue 7, 2018 Edition,
  193. Copyright (C) 2018 by the Institute of
  194. Electrical and Electronics Engineers, Inc and The Open Group.
  195. In the event of any discrepancy between this version and the original IEEE and
  196. The Open Group Standard, the original IEEE and The Open Group Standard
  197. is the referee document. The original Standard can be obtained online at
  198. http://www.opengroup.org/unix/online.html .
  199. .PP
  200. Any typographical or formatting errors that appear
  201. in this page are most likely
  202. to have been introduced during the conversion of the source files to
  203. man page format. To report such errors, see
  204. https://www.kernel.org/doc/man-pages/reporting_bugs.html .