original/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 2015-01-22 "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 .sp
  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 .sp
  40 .in -4n
  41 Feature Test Macro Requirements for glibc (see
  42 .BR feature_test_macros (7)):
  43 .in
  44 .ad l
  45 .PD 0
  46 .sp
  47 .BR utimensat ():
  48 .RS 4
  49 .TP 4
  50 Since glibc 2.10:
  51 _XOPEN_SOURCE\ >=\ 700 || _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 _XOPEN_SOURCE\ >=\ 700 || _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 .\" FIXME . Say something about O_SEARCH?  (But it's not in current
 194 .\" glibc (Mar 08), or kernel 2.6.25.)
 195
 196 If
 197 .I pathname
 198 is relative and
 199 .I dirfd
 200 is the special value
 201 .BR AT_FDCWD ,
 202 then
 203 .I pathname
 204 is interpreted relative to the current working
 205 directory of the calling process (like
 206 .BR utimes (2)).
 207
 208 If
 209 .I pathname
 210 is absolute, then
 211 .I dirfd
 212 is ignored.
 213
 214 The
 215 .I flags
 216 field is a bit mask that may be 0, or include the following constant,
 217 defined in
 218 .IR <fcntl.h> :
 219 .TP
 220 .B AT_SYMLINK_NOFOLLOW
 221 If
 222 .I pathname
 223 specifies a symbolic link, then update the timestamps of the link,
 224 rather than the file to which it refers.
 225 .SH RETURN VALUE
 226 On success,
 227 .BR utimensat ()
 228 and
 229 .BR futimens ()
 230 return 0.
 231 On error, \-1 is returned and
 232 .I errno
 233 is set to indicate the error.
 234 .SH ERRORS
 235 .TP
 236 .B EACCES
 237 .I times
 238 is NULL,
 239 or both
 240 .I tv_nsec
 241 values are
 242 .BR UTIME_NOW ,
 243 and:
 244 .PD 0
 245 .RS
 246 .IP * 2
 247 the effective user ID of the caller does not match
 248 the owner of the file,
 249 the caller does not have write access to the file,
 250 and the caller is not privileged
 251 (Linux: does not have either the
 252 .B CAP_FOWNER
 253 or the
 254 .B CAP_DAC_OVERRIDE
 255 capability); or,
 256 .\" But Linux 2.6.22 was broken here.
 257 .\" Traditionally, utime()/utimes() gives the error EACCES for the case
 258 .\" where the timestamp pointer argument is NULL (i.e., set both timestamps
 259 .\" to the current time), and the file is owned by a user other than the
 260 .\" effective UID of the caller, and the file is not writable by the
 261 .\" effective UID of the program.  utimensat() also gives this error in the
 262 .\" same case.  However, in the same circumstances, when utimensat() is
 263 .\" given a 'times' array in which both tv_nsec fields are UTIME_NOW, which
 264 .\" provides equivalent functionality to specifying 'times' as NULL, the
 265 .\" call succeeds.  It should fail with the error EACCES in this case.
 266 .\"
 267 .\" POSIX.1-2008 has the following:
 268 .\" .TP
 269 .\" .B EACCES
 270 .\" .RB ( utimensat ())
 271 .\" .I fd
 272 .\" was not opened with
 273 .\" .B O_SEARCH
 274 .\" and the permissions of the directory to which
 275 .\" .I fd
 276 .\" refers do not allow searches.
 277 .IP *
 278 the file is marked immutable (see
 279 .BR chattr (1)).
 280 .\" EXT2_IMMUTABLE_FL and similar flags for other filesystems.
 281 .RE
 282 .PD
 283 .TP
 284 .B EBADF
 285 .RB ( futimens ())
 286 .I fd
 287 is not a valid file descriptor.
 288 .TP
 289 .B EBADF
 290 .RB ( utimensat ())
 291 .I pathname
 292 is a relative pathname, but
 293 .I dirfd
 294 is neither
 295 .BR AT_FDCWD
 296 nor a valid file descriptor.
 297 .TP
 298 .B EFAULT
 299 .I times
 300 pointed to an invalid address; or,
 301 .I dirfd
 302 was
 303 .BR AT_FDCWD ,
 304 and
 305 .I pathname
 306 is NULL or an invalid address.
 307 .TP
 308 .B EINVAL
 309 Invalid value in
 310 .IR flags .
 311 .TP
 312 .B EINVAL
 313 Invalid value in one of the
 314 .I tv_nsec
 315 fields (value outside range 0 to 999,999,999, and not
 316 .B UTIME_NOW
 317 or
 318 .BR UTIME_OMIT );
 319 or an invalid value in one of the
 320 .I tv_sec
 321 fields.
 322 .TP
 323 .B EINVAL
 324 .\" SUSv4 does not specify this error.
 325 .I pathname
 326 is NULL,
 327 .I dirfd
 328 is not
 329 .BR AT_FDCWD ,
 330 and
 331 .I flags
 332 contains
 333 .BR AT_SYMLINK_NOFOLLOW .
 334 .TP
 335 .B ELOOP
 336 .RB ( utimensat ())
 337 Too many symbolic links were encountered in resolving
 338 .IR pathname .
 339 .TP
 340 .B ENAMETOOLONG
 341 .RB ( utimensat ())
 342 .I pathname
 343 is too long.
 344 .TP
 345 .B ENOENT
 346 .RB ( utimensat ())
 347 A component of
 348 .I pathname
 349 does not refer to an existing directory or file,
 350 or
 351 .I pathname
 352 is an empty string.
 353 .TP
 354 .B ENOTDIR
 355 .RB ( utimensat ())
 356 .I pathname
 357 is a relative pathname, but
 358 .I dirfd
 359 is neither
 360 .B AT_FDCWD
 361 nor a file descriptor referring to a directory;
 362 or, one of the prefix components of
 363 .I pathname
 364 is not a directory.
 365 .TP
 366 .B EPERM
 367 The caller attempted to change one or both timestamps to a value
 368 other than the current time,
 369 or to change one of the timestamps to the current time while
 370 leaving the other timestamp unchanged,
 371 (i.e.,
 372 .I times
 373 is not NULL, neither
 374 .I tv_nsec
 375 field is
 376 .BR UTIME_NOW ,
 377 and neither
 378 .I tv_nsec
 379 field is
 380 .BR UTIME_OMIT )
 381 and:
 382 .PD 0
 383 .RS
 384 .IP * 2
 385 the caller's effective user ID does not match the owner of file,
 386 and the caller is not privileged
 387 (Linux: does not have the
 388 .BR CAP_FOWNER
 389 capability); or,
 390 .IP *
 391 .\" Linux 2.6.22 was broken here:
 392 .\" it was not consistent with the old utimes() implementation,
 393 .\" since the case when both tv_nsec fields are UTIME_NOW, was not
 394 .\" treated like the (times == NULL) case.
 395 the file is marked append-only or immutable (see
 396 .BR chattr (1)).
 397 .\" EXT2_IMMUTABLE_FL EXT_APPPEND_FL and similar flags for
 398 .\" other filesystems.
 399 .\"
 400 .\" Why the inconsistency (which is described under NOTES) between
 401 .\" EACCES and EPERM, where only EPERM tests for append-only.
 402 .\" (This was also so for the older utimes() implementation.)
 403 .RE
 404 .PD
 405 .TP
 406 .B EROFS
 407 The file is on a read-only filesystem.
 408 .TP
 409 .B ESRCH
 410 .RB ( utimensat ())
 411 Search permission is denied for one of the prefix components of
 412 .IR pathname .
 413 .SH VERSIONS
 414 .BR utimensat ()
 415 was added to Linux in kernel 2.6.22;
 416 glibc support was added with version 2.6.
 417
 418 Support for
 419 .BR futimens ()
 420 first appeared in glibc 2.6.
 421 .SH CONFORMING TO
 422 .BR futimens ()
 423 and
 424 .BR utimensat ()
 425 are specified in POSIX.1-2008.
 426 .SH NOTES
 427 .BR utimensat ()
 428 obsoletes
 429 .BR futimesat (2).
 430
 431 On Linux, timestamps cannot be changed for a file marked immutable,
 432 and the only change permitted for files marked append-only is to
 433 set the timestamps to the current time.
 434 (This is consistent with the historical behavior of
 435 .BR utime (2)
 436 and
 437 .BR utimes (2)
 438 on Linux.)
 439
 440 On Linux,
 441 .BR futimens ()
 442 is a library function implemented on top of the
 443 .BR utimensat ()
 444 system call.
 445 To support this, the Linux
 446 .BR utimensat ()
 447 system call implements a nonstandard feature: if
 448 .I pathname
 449 is NULL, then the call modifies the timestamps of
 450 the file referred to by the file descriptor
 451 .I dirfd
 452 (which may refer to any type of file).
 453 Using this feature, the call
 454 .I "futimens(fd,\ times)"
 455 is implemented as:
 456 .nf
 457
 458     utimensat(fd, NULL, times, 0);
 459 .fi
 460
 461 If both
 462 .I tv_nsec
 463 fields are specified as
 464 .BR UTIME_OMIT ,
 465 then the Linux implementation of
 466 .BR utimensat ()
 467 succeeds even if the file referred to by
 468 .IR dirfd
 469 and
 470 .I pathname
 471 does not exist.
 472 .SH BUGS
 473 Several bugs afflict
 474 .BR utimensat ()
 475 and
 476 .BR futimens ()
 477 on kernels before 2.6.26.
 478 These bugs are either nonconformances with the POSIX.1 draft specification
 479 or inconsistencies with historical Linux behavior.
 480 .IP * 2
 481 POSIX.1 specifies that if one of the
 482 .I tv_nsec
 483 fields has the value
 484 .B UTIME_NOW
 485 or
 486 .BR UTIME_OMIT ,
 487 then the value of the corresponding
 488 .I tv_sec
 489 field should be ignored.
 490 Instead, the value of the
 491 .I tv_sec
 492 field is required to be 0 (or the error
 493 .B EINVAL
 494 results).
 495 .IP *
 496 Various bugs mean that for the purposes of permission checking,
 497 the case where both
 498 .I tv_nsec
 499 fields are set to
 500 .BR UTIME_NOW
 501 isn't always treated the same as specifying
 502 .I times
 503 as NULL,
 504 and the case where one
 505 .I tv_nsec
 506 value is
 507 .B UTIME_NOW
 508 and the other is
 509 .B UTIME_OMIT
 510 isn't treated the same as specifying
 511 .I times
 512 as a pointer to an array of structures containing arbitrary time values.
 513 As a result, in some cases:
 514 a) file timestamps can be updated by a process that shouldn't have
 515 permission to perform updates;
 516 b) file timestamps can't be updated by a process that should have
 517 permission to perform updates; and
 518 c) the wrong
 519 .I errno
 520 value is returned in case of an error.
 521 .\" Below, the long description of the errors from the previous bullet
 522 .\" point (abridged because it's too much detail for a man page).
 523 .\" .IP *
 524 .\" If one of the
 525 .\" .I tv_nsec
 526 .\" fields is
 527 .\" .BR UTIME_OMIT
 528 .\" and the other is
 529 .\" .BR UTIME_NOW ,
 530 .\" then the error
 531 .\" .B EPERM
 532 .\" should occur if the process's effective user ID does not match
 533 .\" the file owner and the process is not privileged.
 534 .\" Instead, the call successfully changes one of the timestamps.
 535 .\" .IP *
 536 .\" If file is not writable by the effective user ID of the process and
 537 .\" the process's effective user ID does not match the file owner and
 538 .\" the process is not privileged,
 539 .\" and
 540 .\" .I times
 541 .\" is NULL, then the error
 542 .\" .B EACCES
 543 .\" results.
 544 .\" This error should also occur if
 545 .\" .I times
 546 .\" points to an array of structures in which both
 547 .\" .I tv_nsec
 548 .\" fields are
 549 .\" .BR UTIME_NOW .
 550 .\" Instead the call succeeds.
 551 .\" .IP *
 552 .\" If a file is marked as append-only (see
 553 .\" .BR chattr (1)),
 554 .\" then Linux traditionally
 555 .\" (i.e.,
 556 .\" .BR utime (2),
 557 .\" .BR utimes (2)),
 558 .\" permits a NULL
 559 .\" .I times
 560 .\" argument to be used in order to update both timestamps to the current time.
 561 .\" For consistency,
 562 .\" .BR utimensat ()
 563 .\" and
 564 .\" .BR futimens ()
 565 .\" should also produce the same result when given a
 566 .\" .I times
 567 .\" argument that points to an array of structures in which both
 568 .\" .I tv_nsec
 569 .\" fields are
 570 .\" .BR UTIME_NOW .
 571 .\" Instead, the call fails with the error
 572 .\" .BR EPERM .
 573 .\" .IP *
 574 .\" If a file is marked as immutable (see
 575 .\" .BR chattr (1)),
 576 .\" then Linux traditionally
 577 .\" (i.e.,
 578 .\" .BR utime (2),
 579 .\" .BR utimes (2)),
 580 .\" gives an
 581 .\" .B EACCES
 582 .\" error if
 583 .\" .I times
 584 .\" is NULL.
 585 .\" For consistency,
 586 .\" .BR utimensat ()
 587 .\" and
 588 .\" .BR futimens ()
 589 .\" should also produce the same result when given a
 590 .\" .I times
 591 .\" that points to an array of structures in which both
 592 .\" .I tv_nsec
 593 .\" fields are
 594 .\" .BR UTIME_NOW .
 595 .\" Instead, the call fails with the error
 596 .\" .BR EPERM .
 597 .IP *
 598 POSIX.1 says that a process that has \fIwrite access to the file\fP
 599 can make a call with
 600 .I times
 601 as NULL, or with
 602 .I times
 603 pointing to an array of structures in which both
 604 .I tv_nsec
 605 fields are
 606 .BR UTIME_NOW ,
 607 in order to update both timestamps to the current time.
 608 However,
 609 .BR futimens ()
 610 instead checks whether the
 611 .IR "access mode of the file descriptor allows writing" .
 612 .\" This means that a process with a file descriptor that allows
 613 .\" writing could change the timestamps of a file for which it
 614 .\" does not have write permission;
 615 .\" conversely, a process with a read-only file descriptor won't
 616 .\" be able to update the timestamps of a file,
 617 .\" even if it has write permission on the file.
 618 .SH SEE ALSO
 619 .BR chattr (1),
 620 .BR futimesat (2),
 621 .BR openat (2),
 622 .BR stat (2),
 623 .BR utimes (2),
 624 .BR futimes (3),
 625 .BR path_resolution (7),
 626 .BR symlink (7)
 627 .SH COLOPHON
 628 This page is part of release 3.79 of the Linux
 629 .I man-pages
 630 project.
 631 A description of the project,
 632 information about reporting bugs,
 633 and the latest version of this page,
 634 can be found at
 635 \%http://www.kernel.org/doc/man\-pages/.