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