.nf
.BR "#include <fcntl.h>" " /* Definition of " AT_* " constants */"
.B #include <sys/stat.h>
-.PP
+.P
.BI "int utimensat(int " dirfd ", const char *" pathname ,
.BI " const struct timespec " times "[_Nullable 2], int " flags );
.BI "int futimens(int " fd ", const struct timespec " times "[_Nullable 2]);"
.fi
-.PP
+.P
.RS -4
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.RE
-.PP
+.P
.BR utimensat ():
.nf
Since glibc 2.10:
Before glibc 2.10:
_ATFILE_SOURCE
.fi
-.PP
+.P
.BR futimens ():
.nf
Since glibc 2.10:
.BR utimes (2),
which permit only second and microsecond precision, respectively,
when setting file timestamps.
-.PP
+.P
With
.BR utimensat ()
the file is specified via the pathname given in
the file whose timestamps are to be updated is specified via
an open file descriptor,
.IR fd .
-.PP
+.P
For both calls, the new file timestamps are specified in the array
.IR times :
.I times[0]
This information is conveyed in a
.BR timespec (3)
structure.
-.PP
+.P
Updated file timestamps are set to the greatest value
supported by the filesystem that is not greater than the specified time.
-.PP
+.P
If the
.I tv_nsec
field of one of the
.I tv_sec
.\" 2.6.22 was broken: it is not ignored
field is ignored.
-.PP
+.P
If
.I times
is NULL, then both timestamps are set to the current time.
.\"
-.PP
+.P
The status change time (ctime) will be set to the current time, even if the
other time stamps don't actually change.
.SS Permissions requirements
the caller's effective user ID must match the owner of the file; or
.IP \[bu]
the caller must have appropriate privileges.
-.PP
+.P
To make any change other than setting both timestamps to the
current time (i.e.,
.I times
field is
.BR UTIME_OMIT ),
either condition 2 or 3 above must apply.
-.PP
+.P
If both
.I tv_nsec
fields are specified as
See
.BR openat (2)
for an explanation of why this can be useful.
-.PP
+.P
If
.I pathname
is relative and
is interpreted relative to the current working
directory of the calling process (like
.BR utimes (2)).
-.PP
+.P
If
.I pathname
is absolute, then
.I dirfd
is ignored.
-.PP
+.P
The
.I flags
field is a bit mask that may be 0, or include the following constant,
Using this feature, the call
.I "futimens(fd,\ times)"
is implemented as:
-.PP
+.P
.in +4n
.EX
utimensat(fd, NULL, times, 0);
.EE
.in
-.PP
+.P
Note, however, that the glibc wrapper for
.BR utimensat ()
disallows passing NULL as the value for
.BR utimensat ()
obsoletes
.BR futimesat (2).
-.PP
+.P
On Linux, timestamps cannot be changed for a file marked immutable,
and the only change permitted for files marked append-only is to
set the timestamps to the current time.
and
.BR utimes (2)
on Linux.)
-.PP
+.P
If both
.I tv_nsec
fields are specified as