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-05-03 "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
  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
  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
  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 .in +4n
 102 .nf
 103
 104 struct timespec {
 105     time_t tv_sec;        /* seconds */
 106     long   tv_nsec;       /* nanoseconds */
 107 };
 108 .fi
 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
 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
 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
 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
 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
 206 If
 207 .I pathname
 208 is absolute, then
 209 .I dirfd
 210 is ignored.
 211
 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
 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
 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
 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
 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 .nf
 477
 478     utimensat(fd, NULL, times, 0);
 479 .fi
 480
 481 Note, however, that the glibc wrapper for
 482 .BR utimensat ()
 483 disallows passing NULL as the value for
 484 .IR file :
 485 the wrapper function returns the error
 486 .IR EINVAL
 487 in this case.
 488 .SH BUGS
 489 Several bugs afflict
 490 .BR utimensat ()
 491 and
 492 .BR futimens ()
 493 on kernels before 2.6.26.
 494 These bugs are either nonconformances with the POSIX.1 draft specification
 495 or inconsistencies with historical Linux behavior.
 496 .IP * 3
 497 POSIX.1 specifies that if one of the
 498 .I tv_nsec
 499 fields has the value
 500 .B UTIME_NOW
 501 or
 502 .BR UTIME_OMIT ,
 503 then the value of the corresponding
 504 .I tv_sec
 505 field should be ignored.
 506 Instead, the value of the
 507 .I tv_sec
 508 field is required to be 0 (or the error
 509 .B EINVAL
 510 results).
 511 .IP *
 512 Various bugs mean that for the purposes of permission checking,
 513 the case where both
 514 .I tv_nsec
 515 fields are set to
 516 .BR UTIME_NOW
 517 isn't always treated the same as specifying
 518 .I times
 519 as NULL,
 520 and the case where one
 521 .I tv_nsec
 522 value is
 523 .B UTIME_NOW
 524 and the other is
 525 .B UTIME_OMIT
 526 isn't treated the same as specifying
 527 .I times
 528 as a pointer to an array of structures containing arbitrary time values.
 529 As a result, in some cases:
 530 a) file timestamps can be updated by a process that shouldn't have
 531 permission to perform updates;
 532 b) file timestamps can't be updated by a process that should have
 533 permission to perform updates; and
 534 c) the wrong
 535 .I errno
 536 value is returned in case of an error.
 537 .\" Below, the long description of the errors from the previous bullet
 538 .\" point (abridged because it's too much detail for a man page).
 539 .\" .IP *
 540 .\" If one of the
 541 .\" .I tv_nsec
 542 .\" fields is
 543 .\" .BR UTIME_OMIT
 544 .\" and the other is
 545 .\" .BR UTIME_NOW ,
 546 .\" then the error
 547 .\" .B EPERM
 548 .\" should occur if the process's effective user ID does not match
 549 .\" the file owner and the process is not privileged.
 550 .\" Instead, the call successfully changes one of the timestamps.
 551 .\" .IP *
 552 .\" If file is not writable by the effective user ID of the process and
 553 .\" the process's effective user ID does not match the file owner and
 554 .\" the process is not privileged,
 555 .\" and
 556 .\" .I times
 557 .\" is NULL, then the error
 558 .\" .B EACCES
 559 .\" results.
 560 .\" This error should also occur if
 561 .\" .I times
 562 .\" points to an array of structures in which both
 563 .\" .I tv_nsec
 564 .\" fields are
 565 .\" .BR UTIME_NOW .
 566 .\" Instead the call succeeds.
 567 .\" .IP *
 568 .\" If a file is marked as append-only (see
 569 .\" .BR chattr (1)),
 570 .\" then Linux traditionally
 571 .\" (i.e.,
 572 .\" .BR utime (2),
 573 .\" .BR utimes (2)),
 574 .\" permits a NULL
 575 .\" .I times
 576 .\" argument to be used in order to update both timestamps to the current time.
 577 .\" For consistency,
 578 .\" .BR utimensat ()
 579 .\" and
 580 .\" .BR futimens ()
 581 .\" should also produce the same result when given a
 582 .\" .I times
 583 .\" argument that points to an array of structures in which both
 584 .\" .I tv_nsec
 585 .\" fields are
 586 .\" .BR UTIME_NOW .
 587 .\" Instead, the call fails with the error
 588 .\" .BR EPERM .
 589 .\" .IP *
 590 .\" If a file is marked as immutable (see
 591 .\" .BR chattr (1)),
 592 .\" then Linux traditionally
 593 .\" (i.e.,
 594 .\" .BR utime (2),
 595 .\" .BR utimes (2)),
 596 .\" gives an
 597 .\" .B EACCES
 598 .\" error if
 599 .\" .I times
 600 .\" is NULL.
 601 .\" For consistency,
 602 .\" .BR utimensat ()
 603 .\" and
 604 .\" .BR futimens ()
 605 .\" should also produce the same result when given a
 606 .\" .I times
 607 .\" that points to an array of structures in which both
 608 .\" .I tv_nsec
 609 .\" fields are
 610 .\" .BR UTIME_NOW .
 611 .\" Instead, the call fails with the error
 612 .\" .BR EPERM .
 613 .IP *
 614 POSIX.1 says that a process that has \fIwrite access to the file\fP
 615 can make a call with
 616 .I times
 617 as NULL, or with
 618 .I times
 619 pointing to an array of structures in which both
 620 .I tv_nsec
 621 fields are
 622 .BR UTIME_NOW ,
 623 in order to update both timestamps to the current time.
 624 However,
 625 .BR futimens ()
 626 instead checks whether the
 627 .IR "access mode of the file descriptor allows writing" .
 628 .\" This means that a process with a file descriptor that allows
 629 .\" writing could change the timestamps of a file for which it
 630 .\" does not have write permission;
 631 .\" conversely, a process with a read-only file descriptor won't
 632 .\" be able to update the timestamps of a file,
 633 .\" even if it has write permission on the file.
 634 .SH SEE ALSO
 635 .BR chattr (1),
 636 .BR touch (1),
 637 .BR futimesat (2),
 638 .BR openat (2),
 639 .BR stat (2),
 640 .BR utimes (2),
 641 .BR futimes (3),
 642 .BR inode (7),
 643 .BR path_resolution (7),
 644 .BR symlink (7)