man2/utimensat.2

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