man2/utimensat.2

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