]>
Commit | Line | Data |
---|---|---|
61dd016f MK |
1 | .\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk |
2 | .\" <mtk.manpages@gmail.com> | |
3 | .\" | |
93015253 | 4 | .\" %%%LICENSE_START(VERBATIM) |
61dd016f MK |
5 | .\" Permission is granted to make and distribute verbatim copies of this |
6 | .\" manual provided the copyright notice and this permission notice are | |
7 | .\" preserved on all copies. | |
8 | .\" | |
9 | .\" Permission is granted to copy and distribute modified versions of this | |
10 | .\" manual under the conditions for verbatim copying, provided that the | |
11 | .\" entire resulting derived work is distributed under the terms of a | |
12 | .\" permission notice identical to this one. | |
13 | .\" | |
14 | .\" Since the Linux kernel and libraries are constantly changing, this | |
15 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
16 | .\" responsibility for errors or omissions, or for damages resulting from | |
17 | .\" the use of the information contained herein. The author(s) may not | |
18 | .\" have taken the same level of care in the production of this manual, | |
19 | .\" which is licensed free of charge, as they might when working | |
20 | .\" professionally. | |
21 | .\" | |
22 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
23 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 24 | .\" %%%LICENSE_END |
61dd016f | 25 | .\" |
4b8c67d9 | 26 | .TH UTIMENSAT 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
61dd016f MK |
27 | .SH NAME |
28 | utimensat, futimens \- change file timestamps with nanosecond precision | |
61dd016f MK |
29 | .SH SYNOPSIS |
30 | .nf | |
3045389f | 31 | .B #include <fcntl.h> /* Definition of AT_* constants */ |
61dd016f | 32 | .B #include <sys/stat.h> |
68e4db0a | 33 | .PP |
61dd016f MK |
34 | .BI "int utimensat(int " dirfd ", const char *" pathname , |
35 | .BI " const struct timespec " times "[2], int " flags ); | |
dbfe9c70 | 36 | .PP |
61dd016f MK |
37 | .BI "int futimens(int " fd ", const struct timespec " times [2]); |
38 | .fi | |
68e4db0a | 39 | .PP |
61dd016f MK |
40 | .in -4n |
41 | Feature Test Macro Requirements for glibc (see | |
42 | .BR feature_test_macros (7)): | |
43 | .in | |
68e4db0a | 44 | .PP |
34c38af8 MK |
45 | .ad l |
46 | .PD 0 | |
61dd016f | 47 | .BR utimensat (): |
34c38af8 MK |
48 | .RS 4 |
49 | .TP 4 | |
50 | Since glibc 2.10: | |
b0da7b8b | 51 | _POSIX_C_SOURCE\ >=\ 200809L |
34c38af8 | 52 | .TP |
7cc796ee | 53 | Before glibc 2.10: |
61dd016f | 54 | _ATFILE_SOURCE |
34c38af8 MK |
55 | .RE |
56 | .PP | |
61dd016f | 57 | .BR futimens (): |
34c38af8 MK |
58 | .RS 4 |
59 | .TP | |
60 | Since glibc 2.10: | |
b0da7b8b | 61 | _POSIX_C_SOURCE\ >=\ 200809L |
34c38af8 | 62 | .TP |
7cc796ee MK |
63 | Before glibc 2.10: |
64 | _GNU_SOURCE | |
34c38af8 MK |
65 | .RE |
66 | .PD | |
67 | .ad | |
61dd016f MK |
68 | .SH DESCRIPTION |
69 | .BR utimensat () | |
70 | and | |
71 | .BR futimens () | |
72 | update the timestamps of a file with nanosecond precision. | |
73 | This contrasts with the historical | |
74 | .BR utime (2) | |
75 | and | |
76 | .BR utimes (2), | |
77 | which permit only second and microsecond precision, respectively, | |
78 | when setting file timestamps. | |
efeece04 | 79 | .PP |
61dd016f MK |
80 | With |
81 | .BR utimensat () | |
82 | the file is specified via the pathname given in | |
83 | .IR pathname . | |
84 | With | |
85 | .BR futimens () | |
86 | the file whose timestamps are to be updated is specified via | |
87 | an open file descriptor, | |
88 | .IR fd . | |
efeece04 | 89 | .PP |
61dd016f MK |
90 | For both calls, the new file timestamps are specified in the array |
91 | .IR times : | |
92 | .IR times [0] | |
93 | specifies the new "last access time" (\fIatime\fP); | |
94 | .IR times [1] | |
95 | specifies the new "last modification time" (\fImtime\fP). | |
96 | Each of the elements of | |
97 | .I times | |
cc3707c0 | 98 | specifies a time as the number of seconds and nanoseconds |
f49c451a MW |
99 | since the Epoch, 1970-01-01 00:00:00 +0000 (UTC). |
100 | This information is conveyed in a structure of the following form: | |
e646a1ba | 101 | .PP |
61dd016f | 102 | .in +4n |
e646a1ba | 103 | .EX |
61dd016f MK |
104 | struct timespec { |
105 | time_t tv_sec; /* seconds */ | |
106 | long tv_nsec; /* nanoseconds */ | |
107 | }; | |
b8302363 | 108 | .EE |
61dd016f MK |
109 | .in |
110 | .PP | |
111 | Updated file timestamps are set to the greatest value | |
9ee4a2b6 | 112 | supported by the filesystem that is not greater than the specified time. |
efeece04 | 113 | .PP |
61dd016f MK |
114 | If the |
115 | .I tv_nsec | |
116 | field of one of the | |
117 | .I timespec | |
118 | structures has the special value | |
119 | .BR UTIME_NOW , | |
120 | then the corresponding file timestamp is set to the current time. | |
121 | If the | |
122 | .I tv_nsec | |
123 | field of one of the | |
124 | .I timespec | |
125 | structures has the special value | |
126 | .BR UTIME_OMIT , | |
127 | then the corresponding file timestamp is left unchanged. | |
128 | In both of these cases, the value of the corresponding | |
129 | .I tv_sec | |
130 | .\" 2.6.22 was broken: it is not ignored | |
131 | field is ignored. | |
efeece04 | 132 | .PP |
61dd016f MK |
133 | If |
134 | .I times | |
135 | is NULL, then both timestamps are set to the current time. | |
136 | .\" | |
137 | .SS Permissions requirements | |
138 | To set both file timestamps to the current time (i.e., | |
139 | .I times | |
140 | is NULL, or both | |
141 | .I tv_nsec | |
142 | fields specify | |
143 | .BR UTIME_NOW ), | |
144 | either: | |
145 | .IP 1. 3 | |
146 | the caller must have write access to the file; | |
147 | .\" 2.6.22 was broken here -- for futimens() the check is | |
148 | .\" based on whether or not the file descriptor is writable, | |
66d90115 | 149 | .\" not on whether the caller's effective UID has write |
61dd016f MK |
150 | .\" permission for the file referred to by the descriptor. |
151 | .IP 2. | |
152 | the caller's effective user ID must match the owner of the file; or | |
153 | .IP 3. | |
154 | the caller must have appropriate privileges. | |
155 | .PP | |
156 | To make any change other than setting both timestamps to the | |
157 | current time (i.e., | |
158 | .I times | |
17068fad | 159 | is not NULL, and neither |
61dd016f | 160 | .I tv_nsec |
17068fad | 161 | field is |
61dd016f MK |
162 | .B UTIME_NOW |
163 | .\" 2.6.22 was broken here: | |
79e20ac1 | 164 | .\" both must be something other than *either* UTIME_OMIT *or* UTIME_NOW. |
17068fad | 165 | and neither |
61dd016f | 166 | .I tv_nsec |
17068fad | 167 | field is |
61dd016f MK |
168 | .BR UTIME_OMIT ), |
169 | either condition 2 or 3 above must apply. | |
efeece04 | 170 | .PP |
61dd016f MK |
171 | If both |
172 | .I tv_nsec | |
173 | fields are specified as | |
174 | .BR UTIME_OMIT , | |
175 | then no file ownership or permission checks are performed, | |
176 | and the file timestamps are not modified, | |
177 | but other error conditions may still be detected. | |
178 | .\" | |
179 | .\" | |
180 | .SS utimensat() specifics | |
181 | If | |
182 | .I pathname | |
183 | is relative, then by default it is interpreted relative to the | |
184 | directory referred to by the open file descriptor, | |
185 | .IR dirfd | |
186 | (rather than relative to the current working directory of | |
187 | the calling process, as is done by | |
188 | .BR utimes (2) | |
189 | for a relative pathname). | |
190 | See | |
191 | .BR openat (2) | |
192 | for an explanation of why this can be useful. | |
efeece04 | 193 | .PP |
61dd016f MK |
194 | If |
195 | .I pathname | |
196 | is relative and | |
197 | .I dirfd | |
198 | is the special value | |
199 | .BR AT_FDCWD , | |
200 | then | |
201 | .I pathname | |
202 | is interpreted relative to the current working | |
203 | directory of the calling process (like | |
204 | .BR utimes (2)). | |
efeece04 | 205 | .PP |
61dd016f MK |
206 | If |
207 | .I pathname | |
208 | is absolute, then | |
209 | .I dirfd | |
210 | is ignored. | |
efeece04 | 211 | .PP |
61dd016f MK |
212 | The |
213 | .I flags | |
214 | field is a bit mask that may be 0, or include the following constant, | |
215 | defined in | |
216 | .IR <fcntl.h> : | |
217 | .TP | |
218 | .B AT_SYMLINK_NOFOLLOW | |
219 | If | |
220 | .I pathname | |
221 | specifies a symbolic link, then update the timestamps of the link, | |
222 | rather than the file to which it refers. | |
47297adb | 223 | .SH RETURN VALUE |
61dd016f MK |
224 | On success, |
225 | .BR utimensat () | |
226 | and | |
227 | .BR futimens () | |
228 | return 0. | |
229 | On error, \-1 is returned and | |
230 | .I errno | |
231 | is set to indicate the error. | |
232 | .SH ERRORS | |
233 | .TP | |
234 | .B EACCES | |
235 | .I times | |
236 | is NULL, | |
237 | or both | |
238 | .I tv_nsec | |
239 | values are | |
240 | .BR UTIME_NOW , | |
1083ffb4 | 241 | and the effective user ID of the caller does not match |
61dd016f MK |
242 | the owner of the file, |
243 | the caller does not have write access to the file, | |
244 | and the caller is not privileged | |
245 | (Linux: does not have either the | |
246 | .B CAP_FOWNER | |
247 | or the | |
248 | .B CAP_DAC_OVERRIDE | |
1083ffb4 | 249 | capability). |
61dd016f MK |
250 | .\" But Linux 2.6.22 was broken here. |
251 | .\" Traditionally, utime()/utimes() gives the error EACCES for the case | |
252 | .\" where the timestamp pointer argument is NULL (i.e., set both timestamps | |
253 | .\" to the current time), and the file is owned by a user other than the | |
254 | .\" effective UID of the caller, and the file is not writable by the | |
255 | .\" effective UID of the program. utimensat() also gives this error in the | |
256 | .\" same case. However, in the same circumstances, when utimensat() is | |
257 | .\" given a 'times' array in which both tv_nsec fields are UTIME_NOW, which | |
258 | .\" provides equivalent functionality to specifying 'times' as NULL, the | |
259 | .\" call succeeds. It should fail with the error EACCES in this case. | |
260 | .\" | |
261 | .\" POSIX.1-2008 has the following: | |
262 | .\" .TP | |
263 | .\" .B EACCES | |
264 | .\" .RB ( utimensat ()) | |
265 | .\" .I fd | |
266 | .\" was not opened with | |
267 | .\" .B O_SEARCH | |
268 | .\" and the permissions of the directory to which | |
269 | .\" .I fd | |
270 | .\" refers do not allow searches. | |
9ee4a2b6 | 271 | .\" EXT2_IMMUTABLE_FL and similar flags for other filesystems. |
61dd016f | 272 | .RE |
61dd016f MK |
273 | .TP |
274 | .B EBADF | |
275 | .RB ( futimens ()) | |
276 | .I fd | |
277 | is not a valid file descriptor. | |
278 | .TP | |
279 | .B EBADF | |
280 | .RB ( utimensat ()) | |
281 | .I pathname | |
282 | is a relative pathname, but | |
283 | .I dirfd | |
284 | is neither | |
285 | .BR AT_FDCWD | |
286 | nor a valid file descriptor. | |
287 | .TP | |
288 | .B EFAULT | |
289 | .I times | |
290 | pointed to an invalid address; or, | |
291 | .I dirfd | |
292 | was | |
293 | .BR AT_FDCWD , | |
294 | and | |
295 | .I pathname | |
296 | is NULL or an invalid address. | |
297 | .TP | |
298 | .B EINVAL | |
299 | Invalid value in | |
300 | .IR flags . | |
301 | .TP | |
302 | .B EINVAL | |
303 | Invalid value in one of the | |
304 | .I tv_nsec | |
305 | fields (value outside range 0 to 999,999,999, and not | |
306 | .B UTIME_NOW | |
307 | or | |
308 | .BR UTIME_OMIT ); | |
309 | or an invalid value in one of the | |
310 | .I tv_sec | |
311 | fields. | |
312 | .TP | |
313 | .B EINVAL | |
314 | .\" SUSv4 does not specify this error. | |
315 | .I pathname | |
316 | is NULL, | |
317 | .I dirfd | |
318 | is not | |
319 | .BR AT_FDCWD , | |
320 | and | |
321 | .I flags | |
322 | contains | |
323 | .BR AT_SYMLINK_NOFOLLOW . | |
324 | .TP | |
325 | .B ELOOP | |
326 | .RB ( utimensat ()) | |
327 | Too many symbolic links were encountered in resolving | |
328 | .IR pathname . | |
329 | .TP | |
330 | .B ENAMETOOLONG | |
331 | .RB ( utimensat ()) | |
332 | .I pathname | |
333 | is too long. | |
334 | .TP | |
335 | .B ENOENT | |
336 | .RB ( utimensat ()) | |
337 | A component of | |
338 | .I pathname | |
339 | does not refer to an existing directory or file, | |
340 | or | |
341 | .I pathname | |
342 | is an empty string. | |
343 | .TP | |
344 | .B ENOTDIR | |
345 | .RB ( utimensat ()) | |
346 | .I pathname | |
347 | is a relative pathname, but | |
348 | .I dirfd | |
349 | is neither | |
350 | .B AT_FDCWD | |
351 | nor a file descriptor referring to a directory; | |
352 | or, one of the prefix components of | |
353 | .I pathname | |
354 | is not a directory. | |
355 | .TP | |
356 | .B EPERM | |
357 | The caller attempted to change one or both timestamps to a value | |
358 | other than the current time, | |
359 | or to change one of the timestamps to the current time while | |
360 | leaving the other timestamp unchanged, | |
361 | (i.e., | |
362 | .I times | |
49f4f33c | 363 | is not NULL, neither |
61dd016f | 364 | .I tv_nsec |
49f4f33c | 365 | field is |
61dd016f | 366 | .BR UTIME_NOW , |
49f4f33c | 367 | and neither |
61dd016f | 368 | .I tv_nsec |
49f4f33c | 369 | field is |
61dd016f | 370 | .BR UTIME_OMIT ) |
47c3854b | 371 | and either: |
61dd016f | 372 | .RS |
47c3854b | 373 | .IP * 3 |
61dd016f MK |
374 | the caller's effective user ID does not match the owner of file, |
375 | and the caller is not privileged | |
376 | (Linux: does not have the | |
377 | .BR CAP_FOWNER | |
378 | capability); or, | |
379 | .IP * | |
380 | .\" Linux 2.6.22 was broken here: | |
381 | .\" it was not consistent with the old utimes() implementation, | |
382 | .\" since the case when both tv_nsec fields are UTIME_NOW, was not | |
383 | .\" treated like the (times == NULL) case. | |
384 | the file is marked append-only or immutable (see | |
385 | .BR chattr (1)). | |
386 | .\" EXT2_IMMUTABLE_FL EXT_APPPEND_FL and similar flags for | |
9ee4a2b6 | 387 | .\" other filesystems. |
61dd016f MK |
388 | .\" |
389 | .\" Why the inconsistency (which is described under NOTES) between | |
390 | .\" EACCES and EPERM, where only EPERM tests for append-only. | |
391 | .\" (This was also so for the older utimes() implementation.) | |
392 | .RE | |
61dd016f MK |
393 | .TP |
394 | .B EROFS | |
9ee4a2b6 | 395 | The file is on a read-only filesystem. |
61dd016f MK |
396 | .TP |
397 | .B ESRCH | |
398 | .RB ( utimensat ()) | |
399 | Search permission is denied for one of the prefix components of | |
400 | .IR pathname . | |
401 | .SH VERSIONS | |
402 | .BR utimensat () | |
403 | was added to Linux in kernel 2.6.22; | |
404 | glibc support was added with version 2.6. | |
efeece04 | 405 | .PP |
61dd016f MK |
406 | Support for |
407 | .BR futimens () | |
408 | first appeared in glibc 2.6. | |
47f06c75 ZL |
409 | .SH ATTRIBUTES |
410 | For an explanation of the terms used in this section, see | |
411 | .BR attributes (7). | |
412 | .TS | |
413 | allbox; | |
414 | lbw23 lb lb | |
415 | l l l. | |
416 | Interface Attribute Value | |
417 | T{ | |
418 | .BR utimensat (), | |
419 | .BR futimens () | |
420 | T} Thread safety MT-Safe | |
421 | .TE | |
efeece04 | 422 | .sp 1 |
47297adb | 423 | .SH CONFORMING TO |
61dd016f MK |
424 | .BR futimens () |
425 | and | |
426 | .BR utimensat () | |
5db9708d | 427 | are specified in POSIX.1-2008. |
61dd016f MK |
428 | .SH NOTES |
429 | .BR utimensat () | |
430 | obsoletes | |
431 | .BR futimesat (2). | |
efeece04 | 432 | .PP |
61dd016f MK |
433 | On Linux, timestamps cannot be changed for a file marked immutable, |
434 | and the only change permitted for files marked append-only is to | |
435 | set the timestamps to the current time. | |
436 | (This is consistent with the historical behavior of | |
437 | .BR utime (2) | |
438 | and | |
439 | .BR utimes (2) | |
440 | on Linux.) | |
efeece04 | 441 | .PP |
2389c1e3 MK |
442 | If both |
443 | .I tv_nsec | |
444 | fields are specified as | |
445 | .BR UTIME_OMIT , | |
446 | then the Linux implementation of | |
447 | .BR utimensat () | |
448 | succeeds even if the file referred to by | |
449 | .IR dirfd | |
450 | and | |
451 | .I pathname | |
452 | does not exist. | |
b146aada | 453 | .SS C library/kernel ABI differences |
61dd016f MK |
454 | On Linux, |
455 | .BR futimens () | |
456 | is a library function implemented on top of the | |
457 | .BR utimensat () | |
458 | system call. | |
459 | To support this, the Linux | |
460 | .BR utimensat () | |
c8f2dd47 | 461 | system call implements a nonstandard feature: if |
61dd016f MK |
462 | .I pathname |
463 | is NULL, then the call modifies the timestamps of | |
464 | the file referred to by the file descriptor | |
465 | .I dirfd | |
466 | (which may refer to any type of file). | |
467 | Using this feature, the call | |
468 | .I "futimens(fd,\ times)" | |
469 | is implemented as: | |
207050fa MK |
470 | .PP |
471 | .in +4n | |
472 | .EX | |
473 | utimensat(fd, NULL, times, 0); | |
474 | .EE | |
475 | .in | |
efeece04 | 476 | .PP |
0fa34fb3 MK |
477 | Note, however, that the glibc wrapper for |
478 | .BR utimensat () | |
479 | disallows passing NULL as the value for | |
af6534dd | 480 | .IR pathname : |
0fa34fb3 MK |
481 | the wrapper function returns the error |
482 | .IR EINVAL | |
483 | in this case. | |
61dd016f MK |
484 | .SH BUGS |
485 | Several bugs afflict | |
486 | .BR utimensat () | |
487 | and | |
488 | .BR futimens () | |
489 | on kernels before 2.6.26. | |
cfea5132 | 490 | These bugs are either nonconformances with the POSIX.1 draft specification |
61dd016f | 491 | or inconsistencies with historical Linux behavior. |
47c3854b | 492 | .IP * 3 |
61dd016f MK |
493 | POSIX.1 specifies that if one of the |
494 | .I tv_nsec | |
495 | fields has the value | |
496 | .B UTIME_NOW | |
497 | or | |
498 | .BR UTIME_OMIT , | |
499 | then the value of the corresponding | |
500 | .I tv_sec | |
501 | field should be ignored. | |
502 | Instead, the value of the | |
503 | .I tv_sec | |
504 | field is required to be 0 (or the error | |
505 | .B EINVAL | |
506 | results). | |
507 | .IP * | |
508 | Various bugs mean that for the purposes of permission checking, | |
509 | the case where both | |
510 | .I tv_nsec | |
511 | fields are set to | |
512 | .BR UTIME_NOW | |
513 | isn't always treated the same as specifying | |
514 | .I times | |
515 | as NULL, | |
516 | and the case where one | |
517 | .I tv_nsec | |
518 | value is | |
519 | .B UTIME_NOW | |
520 | and the other is | |
521 | .B UTIME_OMIT | |
522 | isn't treated the same as specifying | |
523 | .I times | |