Debian Codegraph @

upstream/debian-trixie/man2/utimensat.2

raw
1 '\" t
2 .\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk
3 .\" <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .TH utimensat 2 2024-05-02 "Linux man-pages 6.9.1"
8 .SH NAME
9 utimensat, futimens \- change file timestamps with nanosecond precision
10 .SH LIBRARY
11 Standard C library
12 .RI ( libc ", " \-lc )
13 .SH SYNOPSIS
14 .nf
15 .BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
16 .B #include <sys/stat.h>
17 .P
18 .BI "int utimensat(int " dirfd ", const char *" pathname ,
19 .BI " const struct timespec " times "[_Nullable 2], int " flags );
20 .BI "int futimens(int " fd ", const struct timespec " times "[_Nullable 2]);"
21 .fi
22 .P
23 .RS -4
24 Feature Test Macro Requirements for glibc (see
25 .BR feature_test_macros (7)):
26 .RE
27 .P
28 .BR utimensat ():
29 .nf
30 Since glibc 2.10:
31 _POSIX_C_SOURCE >= 200809L
32 Before glibc 2.10:
33 _ATFILE_SOURCE
34 .fi
35 .P
36 .BR futimens ():
37 .nf
38 Since glibc 2.10:
39 _POSIX_C_SOURCE >= 200809L
40 Before glibc 2.10:
41 _GNU_SOURCE
42 .fi
43 .SH DESCRIPTION
44 .BR utimensat ()
45 and
46 .BR futimens ()
47 update the timestamps of a file with nanosecond precision.
48 This contrasts with the historical
49 .BR utime (2)
50 and
51 .BR utimes (2),
52 which permit only second and microsecond precision, respectively,
53 when setting file timestamps.
54 .P
55 With
56 .BR utimensat ()
57 the file is specified via the pathname given in
58 .IR pathname .
59 With
60 .BR futimens ()
61 the file whose timestamps are to be updated is specified via
62 an open file descriptor,
63 .IR fd .
64 .P
65 For both calls, the new file timestamps are specified in the array
66 .IR times :
67 .I times[0]
68 specifies the new "last access time" (\fIatime\fP);
69 .I times[1]
70 specifies the new "last modification time" (\fImtime\fP).
71 Each of the elements of
72 .I times
73 specifies a time as the number of seconds and nanoseconds
74 since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
75 This information is conveyed in a
76 .BR timespec (3)
77 structure.
78 .P
79 Updated file timestamps are set to the greatest value
80 supported by the filesystem that is not greater than the specified time.
81 .P
82 If the
83 .I tv_nsec
84 field of one of the
85 .I timespec
86 structures has the special value
87 .BR UTIME_NOW ,
88 then the corresponding file timestamp is set to the current time.
89 If the
90 .I tv_nsec
91 field of one of the
92 .I timespec
93 structures has the special value
94 .BR UTIME_OMIT ,
95 then the corresponding file timestamp is left unchanged.
96 In both of these cases, the value of the corresponding
97 .I tv_sec
98 .\" 2.6.22 was broken: it is not ignored
99 field is ignored.
100 .P
101 If
102 .I times
103 is NULL, then both timestamps are set to the current time.
104 .\"
105 .P
106 The status change time (ctime) will be set to the current time, even if the
107 other time stamps don't actually change.
108 .SS Permissions requirements
109 To set both file timestamps to the current time (i.e.,
110 .I times
111 is NULL, or both
112 .I tv_nsec
113 fields specify
114 .BR UTIME_NOW ),
115 either:
116 .IP \[bu] 3
117 the caller must have write access to the file;
118 .\" 2.6.22 was broken here -- for futimens() the check is
119 .\" based on whether or not the file descriptor is writable,
120 .\" not on whether the caller's effective UID has write
121 .\" permission for the file referred to by the descriptor.
122 .IP \[bu]
123 the caller's effective user ID must match the owner of the file; or
124 .IP \[bu]
125 the caller must have appropriate privileges.
126 .P
127 To make any change other than setting both timestamps to the
128 current time (i.e.,
129 .I times
130 is not NULL, and neither
131 .I tv_nsec
132 field is
133 .B UTIME_NOW
134 .\" 2.6.22 was broken here:
135 .\" both must be something other than *either* UTIME_OMIT *or* UTIME_NOW.
136 and neither
137 .I tv_nsec
138 field is
139 .BR UTIME_OMIT ),
140 either condition 2 or 3 above must apply.
141 .P
142 If both
143 .I tv_nsec
144 fields are specified as
145 .BR UTIME_OMIT ,
146 then no file ownership or permission checks are performed,
147 and the file timestamps are not modified,
148 but other error conditions may still be detected.
149 .\"
150 .\"
151 .SS utimensat() specifics
152 If
153 .I pathname
154 is relative, then by default it is interpreted relative to the
155 directory referred to by the open file descriptor,
156 .I dirfd
157 (rather than relative to the current working directory of
158 the calling process, as is done by
159 .BR utimes (2)
160 for a relative pathname).
161 See
162 .BR openat (2)
163 for an explanation of why this can be useful.
164 .P
165 If
166 .I pathname
167 is relative and
168 .I dirfd
169 is the special value
170 .BR AT_FDCWD ,
171 then
172 .I pathname
173 is interpreted relative to the current working
174 directory of the calling process (like
175 .BR utimes (2)).
176 .P
177 If
178 .I pathname
179 is absolute, then
180 .I dirfd
181 is ignored.
182 .P
183 The
184 .I flags
185 argument is a bit mask created by ORing together zero or more of
186 the following values defined in
187 .IR <fcntl.h> :
188 .TP
189 .BR AT_EMPTY_PATH " (since Linux 5.8)"
190 If
191 .I pathname
192 is an empty string, operate on the file referred to by
193 .I dirfd
194 (which may have been obtained using the
195 .BR open (2)
196 .B O_PATH
197 flag).
198 In this case,
199 .I dirfd
200 can refer to any type of file, not just a directory.
201 If
202 .I dirfd
203 is
204 .BR AT_FDCWD ,
205 the call operates on the current working directory.
206 This flag is Linux-specific; define
207 .B _GNU_SOURCE
208 to obtain its definition.
209 .TP
210 .B AT_SYMLINK_NOFOLLOW
211 If
212 .I pathname
213 specifies a symbolic link, then update the timestamps of the link,
214 rather than the file to which it refers.
215 .SH RETURN VALUE
216 On success,
217 .BR utimensat ()
218 and
219 .BR futimens ()
220 return 0.
221 On error, \-1 is returned and
222 .I errno
223 is set to indicate the error.
224 .SH ERRORS
225 .TP
226 .B EACCES
227 .I times
228 is NULL,
229 or both
230 .I tv_nsec
231 values are
232 .BR UTIME_NOW ,
233 and the effective user ID of the caller does not match
234 the owner of the file,
235 the caller does not have write access to the file,
236 and the caller is not privileged
237 (Linux: does not have either the
238 .B CAP_FOWNER
239 or the
240 .B CAP_DAC_OVERRIDE
241 capability).
242 .\" But Linux 2.6.22 was broken here.
243 .\" Traditionally, utime()/utimes() gives the error EACCES for the case
244 .\" where the timestamp pointer argument is NULL (i.e., set both timestamps
245 .\" to the current time), and the file is owned by a user other than the
246 .\" effective UID of the caller, and the file is not writable by the
247 .\" effective UID of the program. utimensat() also gives this error in the
248 .\" same case. However, in the same circumstances, when utimensat() is
249 .\" given a 'times' array in which both tv_nsec fields are UTIME_NOW, which
250 .\" provides equivalent functionality to specifying 'times' as NULL, the
251 .\" call succeeds. It should fail with the error EACCES in this case.
252 .\"
253 .\" POSIX.1-2008 has the following:
254 .\" .TP
255 .\" .B EACCES
256 .\" .RB ( utimensat ())
257 .\" .I fd
258 .\" was not opened with
259 .\" .B O_SEARCH
260 .\" and the permissions of the directory to which
261 .\" .I fd
262 .\" refers do not allow searches.
263 .\" EXT2_IMMUTABLE_FL and similar flags for other filesystems.
264 .TP
265 .B EBADF
266 .RB ( futimens ())
267 .I fd
268 is not a valid file descriptor.
269 .TP
270 .B EBADF
271 .RB ( utimensat ())
272 .I pathname
273 is relative but
274 .I dirfd
275 is neither
276 .B AT_FDCWD
277 nor a valid file descriptor.
278 .TP
279 .B EFAULT
280 .I times
281 pointed to an invalid address; or,
282 .I dirfd
283 was
284 .BR AT_FDCWD ,
285 and
286 .I pathname
287 is NULL or an invalid address.
288 .TP
289 .B EINVAL
290 Invalid value in
291 .IR flags .
292 .TP
293 .B EINVAL
294 Invalid value in one of the
295 .I tv_nsec
296 fields (value outside range [0, 999,999,999], and not
297 .B UTIME_NOW
298 or
299 .BR UTIME_OMIT );
300 or an invalid value in one of the
301 .I tv_sec
302 fields.
303 .TP
304 .B EINVAL
305 .\" SUSv4 does not specify this error.
306 .I pathname
307 is NULL,
308 .I dirfd
309 is not
310 .BR AT_FDCWD ,
311 and
312 .I flags
313 contains
314 .BR AT_SYMLINK_NOFOLLOW .
315 .TP
316 .B ELOOP
317 .RB ( utimensat ())
318 Too many symbolic links were encountered in resolving
319 .IR pathname .
320 .TP
321 .B ENAMETOOLONG
322 .RB ( utimensat ())
323 .I pathname
324 is too long.
325 .TP
326 .B ENOENT
327 .RB ( utimensat ())
328 A component of
329 .I pathname
330 does not refer to an existing directory or file,
331 or
332 .I pathname
333 is an empty string.
334 .TP
335 .B ENOTDIR
336 .RB ( utimensat ())
337 .I pathname
338 is a relative pathname, but
339 .I dirfd
340 is neither
341 .B AT_FDCWD
342 nor a file descriptor referring to a directory;
343 or, one of the prefix components of
344 .I pathname
345 is not a directory.
346 .TP
347 .B EPERM
348 The caller attempted to change one or both timestamps to a value
349 other than the current time,
350 or to change one of the timestamps to the current time while
351 leaving the other timestamp unchanged,
352 (i.e.,
353 .I times
354 is not NULL, neither
355 .I tv_nsec
356 field is
357 .BR UTIME_NOW ,
358 and neither
359 .I tv_nsec
360 field is
361 .BR UTIME_OMIT )
362 and either:
363 .RS
364 .IP \[bu] 3
365 the caller's effective user ID does not match the owner of file,
366 and the caller is not privileged
367 (Linux: does not have the
368 .B CAP_FOWNER
369 capability); or,
370 .IP \[bu]
371 .\" Linux 2.6.22 was broken here:
372 .\" it was not consistent with the old utimes() implementation,
373 .\" since the case when both tv_nsec fields are UTIME_NOW, was not
374 .\" treated like the (times == NULL) case.
375 the file is marked append-only or immutable (see
376 .BR chattr (1)).
377 .\" EXT2_IMMUTABLE_FL EXT_APPEND_FL and similar flags for
378 .\" other filesystems.
379 .\"
380 .\" Why the inconsistency (which is described under NOTES) between
381 .\" EACCES and EPERM, where only EPERM tests for append-only.
382 .\" (This was also so for the older utimes() implementation.)
383 .RE
384 .TP
385 .B EROFS
386 The file is on a read-only filesystem.
387 .TP
388 .B ESRCH
389 .RB ( utimensat ())
390 Search permission is denied for one of the prefix components of
391 .IR pathname .
392 .SH ATTRIBUTES
393 For an explanation of the terms used in this section, see
394 .BR attributes (7).
395 .TS
396 allbox;
397 lbx lb lb
398 l l l.
399 Interface Attribute Value
400 T{
401 .na
402 .nh
403 .BR utimensat (),
404 .BR futimens ()
405 T} Thread safety MT-Safe
406 .TE
407 .SH VERSIONS
408 .SS C library/kernel ABI differences
409 On Linux,
410 .BR futimens ()
411 is a library function implemented on top of the
412 .BR utimensat ()
413 system call.
414 To support this, the Linux
415 .BR utimensat ()
416 system call implements a nonstandard feature: if
417 .I pathname
418 is NULL, then the call modifies the timestamps of
419 the file referred to by the file descriptor
420 .I dirfd
421 (which may refer to any type of file).
422 Using this feature, the call
423 .I "futimens(fd,\ times)"
424 is implemented as:
425 .P
426 .in +4n
427 .EX
428 utimensat(fd, NULL, times, 0);
429 .EE
430 .in
431 .P
432 Note, however, that the glibc wrapper for
433 .BR utimensat ()
434 disallows passing NULL as the value for
435 .IR pathname :
436 the wrapper function returns the error
437 .B EINVAL
438 in this case.
439 .SH STANDARDS
440 POSIX.1-2008.
441 .SH VERSIONS
442 .TP
443 .BR utimensat ()
444 Linux 2.6.22,
445 glibc 2.6.
446 POSIX.1-2008.
447 .TP
448 .BR futimens ()
449 glibc 2.6.
450 POSIX.1-2008.
451 .SH NOTES
452 .BR utimensat ()
453 obsoletes
454 .BR futimesat (2).
455 .P
456 On Linux, timestamps cannot be changed for a file marked immutable,
457 and the only change permitted for files marked append-only is to
458 set the timestamps to the current time.
459 (This is consistent with the historical behavior of
460 .BR utime (2)
461 and
462 .BR utimes (2)
463 on Linux.)
464 .P
465 If both
466 .I tv_nsec
467 fields are specified as
468 .BR UTIME_OMIT ,
469 then the Linux implementation of
470 .BR utimensat ()
471 succeeds even if the file referred to by
472 .I dirfd
473 and
474 .I pathname
475 does not exist.
476 .SH BUGS
477 Several bugs afflict
478 .BR utimensat ()
479 and
480 .BR futimens ()
481 before Linux 2.6.26.
482 These bugs are either nonconformances with the POSIX.1 draft specification
483 or inconsistencies with historical Linux behavior.
484 .IP \[bu] 3
485 POSIX.1 specifies that if one of the
486 .I tv_nsec
487 fields has the value
488 .B UTIME_NOW
489 or
490 .BR UTIME_OMIT ,
491 then the value of the corresponding
492 .I tv_sec
493 field should be ignored.
494 Instead, the value of the
495 .I tv_sec
496 field is required to be 0 (or the error
497 .B EINVAL
498 results).
499 .IP \[bu]
500 Various bugs mean that for the purposes of permission checking,
501 the case where both
502 .I tv_nsec
503 fields are set to
504 .B UTIME_NOW
505 isn't always treated the same as specifying
506 .I times
507 as NULL,
508 and the case where one
509 .I tv_nsec
510 value is
511 .B UTIME_NOW
512 and the other is
513 .B UTIME_OMIT
514 isn't treated the same as specifying
515 .I times
516 as a pointer to an array of structures containing arbitrary time values.
517 As a result, in some cases:
518 a) file timestamps can be updated by a process that shouldn't have
519 permission to perform updates;
520 b) file timestamps can't be updated by a process that should have
521 permission to perform updates; and
522 c) the wrong
523 .I errno
524 value is returned in case of an error.
525 .\" Below, the long description of the errors from the previous bullet
526 .\" point (abridged because it's too much detail for a man page).
527 .\" .IP \[bu]
528 .\" If one of the
529 .\" .I tv_nsec
530 .\" fields is
531 .\" .BR UTIME_OMIT
532 .\" and the other is
533 .\" .BR UTIME_NOW ,
534 .\" then the error
535 .\" .B EPERM
536 .\" should occur if the process's effective user ID does not match
537 .\" the file owner and the process is not privileged.
538 .\" Instead, the call successfully changes one of the timestamps.
539 .\" .IP \[bu]
540 .\" If file is not writable by the effective user ID of the process and
541 .\" the process's effective user ID does not match the file owner and
542 .\" the process is not privileged,
543 .\" and
544 .\" .I times
545 .\" is NULL, then the error
546 .\" .B EACCES
547 .\" results.
548 .\" This error should also occur if
549 .\" .I times
550 .\" points to an array of structures in which both
551 .\" .I tv_nsec
552 .\" fields are
553 .\" .BR UTIME_NOW .
554 .\" Instead the call succeeds.
555 .\" .IP \[bu]
556 .\" If a file is marked as append-only (see
557 .\" .BR chattr (1)),
558 .\" then Linux traditionally
559 .\" (i.e.,
560 .\" .BR utime (2),
561 .\" .BR utimes (2)),
562 .\" permits a NULL
563 .\" .I times
564 .\" argument to be used in order to update both timestamps to the current time.
565 .\" For consistency,
566 .\" .BR utimensat ()
567 .\" and
568 .\" .BR futimens ()
569 .\" should also produce the same result when given a
570 .\" .I times
571 .\" argument that points to an array of structures in which both
572 .\" .I tv_nsec
573 .\" fields are
574 .\" .BR UTIME_NOW .
575 .\" Instead, the call fails with the error
576 .\" .BR EPERM .
577 .\" .IP \[bu]
578 .\" If a file is marked as immutable (see
579 .\" .BR chattr (1)),
580 .\" then Linux traditionally
581 .\" (i.e.,
582 .\" .BR utime (2),
583 .\" .BR utimes (2)),
584 .\" gives an
585 .\" .B EACCES
586 .\" error if
587 .\" .I times
588 .\" is NULL.
589 .\" For consistency,
590 .\" .BR utimensat ()
591 .\" and
592 .\" .BR futimens ()
593 .\" should also produce the same result when given a
594 .\" .I times
595 .\" that points to an array of structures in which both
596 .\" .I tv_nsec
597 .\" fields are
598 .\" .BR UTIME_NOW .
599 .\" Instead, the call fails with the error
600 .\" .BR EPERM .
601 .IP \[bu]
602 POSIX.1 says that a process that has \fIwrite access to the file\fP
603 can make a call with
604 .I times
605 as NULL, or with
606 .I times
607 pointing to an array of structures in which both
608 .I tv_nsec
609 fields are
610 .BR UTIME_NOW ,
611 in order to update both timestamps to the current time.
612 However,
613 .BR futimens ()
614 instead checks whether the
615 .IR "access mode of the file descriptor allows writing" .
616 .\" This means that a process with a file descriptor that allows
617 .\" writing could change the timestamps of a file for which it
618 .\" does not have write permission;
619 .\" conversely, a process with a read-only file descriptor won't
620 .\" be able to update the timestamps of a file,
621 .\" even if it has write permission on the file.
622 .SH SEE ALSO
623 .BR chattr (1),
624 .BR touch (1),
625 .BR futimesat (2),
626 .BR openat (2),
627 .BR stat (2),
628 .BR utimes (2),
629 .BR futimes (3),
630 .BR timespec (3),
631 .BR inode (7),
632 .BR path_resolution (7),
633 .BR symlink (7)