original/man2/utimensat.2

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