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 2017-09-15 "Linux" "Linux Programmer's Manual"
  27 .SH NAME
  28 utimensat, futimens \- change file timestamps with nanosecond precision
  29 .SH SYNOPSIS
  30 .nf
  31 .B #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 .PP
  37 .BI "int futimens(int " fd ", const struct timespec " times [2]);
  38 .fi
  39 .PP
  40 .in -4n
  41 Feature Test Macro Requirements for glibc (see
  42 .BR feature_test_macros (7)):
  43 .in
  44 .PP
  45 .ad l
  46 .PD 0
  47 .BR utimensat ():
  48 .RS 4
  49 .TP 4
  50 Since glibc 2.10:
  51 _POSIX_C_SOURCE\ >=\ 200809L
  52 .TP
  53 Before glibc 2.10:
  54 _ATFILE_SOURCE
  55 .RE
  56 .PP
  57 .BR futimens ():
  58 .RS 4
  59 .TP
  60 Since glibc 2.10:
  61 _POSIX_C_SOURCE\ >=\ 200809L
  62 .TP
  63 Before glibc 2.10:
  64 _GNU_SOURCE
  65 .RE
  66 .PD
  67 .ad
  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.
  79 .PP
  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 .
  89 .PP
  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
  98 specifies a time as the number of seconds and nanoseconds
  99 since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
 100 This information is conveyed in a structure of the following form:
 101 .PP
 102 .in +4n
 103 .EX
 104 struct timespec {
 105     time_t tv_sec;        /* seconds */
 106     long   tv_nsec;       /* nanoseconds */
 107 };
 108 .EE
 109 .in
 110 .PP
 111 Updated file timestamps are set to the greatest value
 112 supported by the filesystem that is not greater than the specified time.
 113 .PP
 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.
 132 .PP
 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,
 149 .\" not on whether the caller's effective UID has write
 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
 159 is not NULL, and neither
 160 .I tv_nsec
 161 field is
 162 .B UTIME_NOW
 163 .\" 2.6.22 was broken here:
 164 .\" both must be something other than *either* UTIME_OMIT *or* UTIME_NOW.
 165 and neither
 166 .I tv_nsec
 167 field is
 168 .BR UTIME_OMIT ),
 169 either condition 2 or 3 above must apply.
 170 .PP
 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.
 193 .PP
 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)).
 205 .PP
 206 If
 207 .I pathname
 208 is absolute, then
 209 .I dirfd
 210 is ignored.
 211 .PP
 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.
 223 .SH RETURN VALUE
 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 ,
 241 and either:
 242 .RS
 243 .IP * 3
 244 the effective user ID of the caller does not match
 245 the owner of the file,
 246 the caller does not have write access to the file,
 247 and the caller is not privileged
 248 (Linux: does not have either the
 249 .B CAP_FOWNER
 250 or the
 251 .B CAP_DAC_OVERRIDE
 252 capability); or,
 253 .\" But Linux 2.6.22 was broken here.
 254 .\" Traditionally, utime()/utimes() gives the error EACCES for the case
 255 .\" where the timestamp pointer argument is NULL (i.e., set both timestamps
 256 .\" to the current time), and the file is owned by a user other than the
 257 .\" effective UID of the caller, and the file is not writable by the
 258 .\" effective UID of the program.  utimensat() also gives this error in the
 259 .\" same case.  However, in the same circumstances, when utimensat() is
 260 .\" given a 'times' array in which both tv_nsec fields are UTIME_NOW, which
 261 .\" provides equivalent functionality to specifying 'times' as NULL, the
 262 .\" call succeeds.  It should fail with the error EACCES in this case.
 263 .\"
 264 .\" POSIX.1-2008 has the following:
 265 .\" .TP
 266 .\" .B EACCES
 267 .\" .RB ( utimensat ())
 268 .\" .I fd
 269 .\" was not opened with
 270 .\" .B O_SEARCH
 271 .\" and the permissions of the directory to which
 272 .\" .I fd
 273 .\" refers do not allow searches.
 274 .IP *
 275 the file is marked immutable (see
 276 .BR chattr (1)).
 277 .\" EXT2_IMMUTABLE_FL and similar flags for other filesystems.
 278 .RE
 279 .TP
 280 .B EBADF
 281 .RB ( futimens ())
 282 .I fd
 283 is not a valid file descriptor.
 284 .TP
 285 .B EBADF
 286 .RB ( utimensat ())
 287 .I pathname
 288 is a relative pathname, but
 289 .I dirfd
 290 is neither
 291 .BR AT_FDCWD
 292 nor a valid file descriptor.
 293 .TP
 294 .B EFAULT
 295 .I times
 296 pointed to an invalid address; or,
 297 .I dirfd
 298 was
 299 .BR AT_FDCWD ,
 300 and
 301 .I pathname
 302 is NULL or an invalid address.
 303 .TP
 304 .B EINVAL
 305 Invalid value in
 306 .IR flags .
 307 .TP
 308 .B EINVAL
 309 Invalid value in one of the
 310 .I tv_nsec
 311 fields (value outside range 0 to 999,999,999, and not
 312 .B UTIME_NOW
 313 or
 314 .BR UTIME_OMIT );
 315 or an invalid value in one of the
 316 .I tv_sec
 317 fields.
 318 .TP
 319 .B EINVAL
 320 .\" SUSv4 does not specify this error.
 321 .I pathname
 322 is NULL,
 323 .I dirfd
 324 is not
 325 .BR AT_FDCWD ,
 326 and
 327 .I flags
 328 contains
 329 .BR AT_SYMLINK_NOFOLLOW .
 330 .TP
 331 .B ELOOP
 332 .RB ( utimensat ())
 333 Too many symbolic links were encountered in resolving
 334 .IR pathname .
 335 .TP
 336 .B ENAMETOOLONG
 337 .RB ( utimensat ())
 338 .I pathname
 339 is too long.
 340 .TP
 341 .B ENOENT
 342 .RB ( utimensat ())
 343 A component of
 344 .I pathname
 345 does not refer to an existing directory or file,
 346 or
 347 .I pathname
 348 is an empty string.
 349 .TP
 350 .B ENOTDIR
 351 .RB ( utimensat ())
 352 .I pathname
 353 is a relative pathname, but
 354 .I dirfd
 355 is neither
 356 .B AT_FDCWD
 357 nor a file descriptor referring to a directory;
 358 or, one of the prefix components of
 359 .I pathname
 360 is not a directory.
 361 .TP
 362 .B EPERM
 363 The caller attempted to change one or both timestamps to a value
 364 other than the current time,
 365 or to change one of the timestamps to the current time while
 366 leaving the other timestamp unchanged,
 367 (i.e.,
 368 .I times
 369 is not NULL, neither
 370 .I tv_nsec
 371 field is
 372 .BR UTIME_NOW ,
 373 and neither
 374 .I tv_nsec
 375 field is
 376 .BR UTIME_OMIT )
 377 and either:
 378 .RS
 379 .IP * 3
 380 the caller's effective user ID does not match the owner of file,
 381 and the caller is not privileged
 382 (Linux: does not have the
 383 .BR CAP_FOWNER
 384 capability); or,
 385 .IP *
 386 .\" Linux 2.6.22 was broken here:
 387 .\" it was not consistent with the old utimes() implementation,
 388 .\" since the case when both tv_nsec fields are UTIME_NOW, was not
 389 .\" treated like the (times == NULL) case.
 390 the file is marked append-only or immutable (see
 391 .BR chattr (1)).
 392 .\" EXT2_IMMUTABLE_FL EXT_APPPEND_FL and similar flags for
 393 .\" other filesystems.
 394 .\"
 395 .\" Why the inconsistency (which is described under NOTES) between
 396 .\" EACCES and EPERM, where only EPERM tests for append-only.
 397 .\" (This was also so for the older utimes() implementation.)
 398 .RE
 399 .TP
 400 .B EROFS
 401 The file is on a read-only filesystem.
 402 .TP
 403 .B ESRCH
 404 .RB ( utimensat ())
 405 Search permission is denied for one of the prefix components of
 406 .IR pathname .
 407 .SH VERSIONS
 408 .BR utimensat ()
 409 was added to Linux in kernel 2.6.22;
 410 glibc support was added with version 2.6.
 411 .PP
 412 Support for
 413 .BR futimens ()
 414 first appeared in glibc 2.6.
 415 .SH ATTRIBUTES
 416 For an explanation of the terms used in this section, see
 417 .BR attributes (7).
 418 .TS
 419 allbox;
 420 lbw23 lb lb
 421 l l l.
 422 Interface       Attribute       Value
 423 T{
 424 .BR utimensat (),
 425 .BR futimens ()
 426 T}      Thread safety   MT-Safe
 427 .TE
 428 .sp 1
 429 .SH CONFORMING TO
 430 .BR futimens ()
 431 and
 432 .BR utimensat ()
 433 are specified in POSIX.1-2008.
 434 .SH NOTES
 435 .BR utimensat ()
 436 obsoletes
 437 .BR futimesat (2).
 438 .PP
 439 On Linux, timestamps cannot be changed for a file marked immutable,
 440 and the only change permitted for files marked append-only is to
 441 set the timestamps to the current time.
 442 (This is consistent with the historical behavior of
 443 .BR utime (2)
 444 and
 445 .BR utimes (2)
 446 on Linux.)
 447 .PP
 448 If both
 449 .I tv_nsec
 450 fields are specified as
 451 .BR UTIME_OMIT ,
 452 then the Linux implementation of
 453 .BR utimensat ()
 454 succeeds even if the file referred to by
 455 .IR dirfd
 456 and
 457 .I pathname
 458 does not exist.
 459 .SS C library/kernel ABI differences
 460 On Linux,
 461 .BR futimens ()
 462 is a library function implemented on top of the
 463 .BR utimensat ()
 464 system call.
 465 To support this, the Linux
 466 .BR utimensat ()
 467 system call implements a nonstandard feature: if
 468 .I pathname
 469 is NULL, then the call modifies the timestamps of
 470 the file referred to by the file descriptor
 471 .I dirfd
 472 (which may refer to any type of file).
 473 Using this feature, the call
 474 .I "futimens(fd,\ times)"
 475 is implemented as:
 476 .PP
 477 .in +4n
 478 .EX
 479 utimensat(fd, NULL, times, 0);
 480 .EE
 481 .in
 482 .PP
 483 Note, however, that the glibc wrapper for
 484 .BR utimensat ()
 485 disallows passing NULL as the value for
 486 .IR pathname :
 487 the wrapper function returns the error
 488 .IR EINVAL
 489 in this case.
 490 .SH BUGS
 491 Several bugs afflict
 492 .BR utimensat ()
 493 and
 494 .BR futimens ()
 495 on kernels before 2.6.26.
 496 These bugs are either nonconformances with the POSIX.1 draft specification
 497 or inconsistencies with historical Linux behavior.
 498 .IP * 3
 499 POSIX.1 specifies that if one of the
 500 .I tv_nsec
 501 fields has the value
 502 .B UTIME_NOW
 503 or
 504 .BR UTIME_OMIT ,
 505 then the value of the corresponding
 506 .I tv_sec
 507 field should be ignored.
 508 Instead, the value of the
 509 .I tv_sec
 510 field is required to be 0 (or the error
 511 .B EINVAL
 512 results).
 513 .IP *
 514 Various bugs mean that for the purposes of permission checking,
 515 the case where both
 516 .I tv_nsec
 517 fields are set to
 518 .BR UTIME_NOW
 519 isn't always treated the same as specifying
 520 .I times
 521 as NULL,
 522 and the case where one
 523 .I tv_nsec
 524 value is
 525 .B UTIME_NOW
 526 and the other is
 527 .B UTIME_OMIT
 528 isn't treated the same as specifying
 529 .I times
 530 as a pointer to an array of structures containing arbitrary time values.
 531 As a result, in some cases:
 532 a) file timestamps can be updated by a process that shouldn't have
 533 permission to perform updates;
 534 b) file timestamps can't be updated by a process that should have
 535 permission to perform updates; and
 536 c) the wrong
 537 .I errno
 538 value is returned in case of an error.
 539 .\" Below, the long description of the errors from the previous bullet
 540 .\" point (abridged because it's too much detail for a man page).
 541 .\" .IP *
 542 .\" If one of the
 543 .\" .I tv_nsec
 544 .\" fields is
 545 .\" .BR UTIME_OMIT
 546 .\" and the other is
 547 .\" .BR UTIME_NOW ,
 548 .\" then the error
 549 .\" .B EPERM
 550 .\" should occur if the process's effective user ID does not match
 551 .\" the file owner and the process is not privileged.
 552 .\" Instead, the call successfully changes one of the timestamps.
 553 .\" .IP *
 554 .\" If file is not writable by the effective user ID of the process and
 555 .\" the process's effective user ID does not match the file owner and
 556 .\" the process is not privileged,
 557 .\" and
 558 .\" .I times
 559 .\" is NULL, then the error
 560 .\" .B EACCES
 561 .\" results.
 562 .\" This error should also occur if
 563 .\" .I times
 564 .\" points to an array of structures in which both
 565 .\" .I tv_nsec
 566 .\" fields are
 567 .\" .BR UTIME_NOW .
 568 .\" Instead the call succeeds.
 569 .\" .IP *
 570 .\" If a file is marked as append-only (see
 571 .\" .BR chattr (1)),
 572 .\" then Linux traditionally
 573 .\" (i.e.,
 574 .\" .BR utime (2),
 575 .\" .BR utimes (2)),
 576 .\" permits a NULL
 577 .\" .I times
 578 .\" argument to be used in order to update both timestamps to the current time.
 579 .\" For consistency,
 580 .\" .BR utimensat ()
 581 .\" and
 582 .\" .BR futimens ()
 583 .\" should also produce the same result when given a
 584 .\" .I times
 585 .\" argument that points to an array of structures in which both
 586 .\" .I tv_nsec
 587 .\" fields are
 588 .\" .BR UTIME_NOW .
 589 .\" Instead, the call fails with the error
 590 .\" .BR EPERM .
 591 .\" .IP *
 592 .\" If a file is marked as immutable (see
 593 .\" .BR chattr (1)),
 594 .\" then Linux traditionally
 595 .\" (i.e.,
 596 .\" .BR utime (2),
 597 .\" .BR utimes (2)),
 598 .\" gives an
 599 .\" .B EACCES
 600 .\" error if
 601 .\" .I times
 602 .\" is NULL.
 603 .\" For consistency,
 604 .\" .BR utimensat ()
 605 .\" and
 606 .\" .BR futimens ()
 607 .\" should also produce the same result when given a
 608 .\" .I times
 609 .\" that points to an array of structures in which both
 610 .\" .I tv_nsec
 611 .\" fields are
 612 .\" .BR UTIME_NOW .
 613 .\" Instead, the call fails with the error
 614 .\" .BR EPERM .
 615 .IP *
 616 POSIX.1 says that a process that has \fIwrite access to the file\fP
 617 can make a call with
 618 .I times
 619 as NULL, or with
 620 .I times
 621 pointing to an array of structures in which both
 622 .I tv_nsec
 623 fields are
 624 .BR UTIME_NOW ,
 625 in order to update both timestamps to the current time.
 626 However,
 627 .BR futimens ()
 628 instead checks whether the
 629 .IR "access mode of the file descriptor allows writing" .
 630 .\" This means that a process with a file descriptor that allows
 631 .\" writing could change the timestamps of a file for which it
 632 .\" does not have write permission;
 633 .\" conversely, a process with a read-only file descriptor won't
 634 .\" be able to update the timestamps of a file,
 635 .\" even if it has write permission on the file.
 636 .SH SEE ALSO
 637 .BR chattr (1),
 638 .BR touch (1),
 639 .BR futimesat (2),
 640 .BR openat (2),
 641 .BR stat (2),
 642 .BR utimes (2),
 643 .BR futimes (3),
 644 .BR inode (7),
 645 .BR path_resolution (7),
 646 .BR symlink (7)