Debian Codegraph @

upstream/debian-unstable/man2/utimensat.2

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