accept.2, execve.2, futimesat.2, getresuid.2, getrlimit.2, madvise.2, mq_getsetattr...

[thirdparty/man-pages.git] / man2 / utimensat.2

.\" Hey Emacs! This file is -*- nroff -*- source.
.\"
.\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk
.\" <mtk.manpages@gmail.com>
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
.\" preserved on all copies.
.\"
.\" Permission is granted to copy and distribute modified versions of this
.\" manual under the conditions for verbatim copying, provided that the
.\" entire resulting derived work is distributed under the terms of a
.\" permission notice identical to this one.
.\"
.\" Since the Linux kernel and libraries are constantly changing, this
.\" manual page may be incorrect or out-of-date.  The author(s) assume no
.\" responsibility for errors or omissions, or for damages resulting from
.\" the use of the information contained herein.  The author(s) may not
.\" have taken the same level of care in the production of this manual,
.\" which is licensed free of charge, as they might when working
.\" professionally.
.\"
.\" Formatted or processed versions of this manual, if unaccompanied by
.\" the source, must acknowledge the copyright and authors of this work.
.\"
.TH UTIMENSAT 2 2009-12-13 "Linux" "Linux Programmer's Manual"
.SH NAME
utimensat, futimens \- change file timestamps with nanosecond precision
.SH SYNOPSIS
.nf
.B #include <sys/stat.h>
.sp
.BI "int utimensat(int " dirfd ", const char *" pathname ,
.BI "              const struct timespec " times "[2], int " flags );

.BI "int futimens(int " fd ", const struct timespec " times [2]);
.fi
.sp
.in -4n
Feature Test Macro Requirements for glibc (see
.BR feature_test_macros (7)):
.in
.sp
.BR utimensat ():
.br
Since glibc 2.10: _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
.br
Before glibc 2.10:
_ATFILE_SOURCE
.br
.BR futimens ():
.br
Since glibc 2.10: _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L
.br
Before glibc 2.10:
_GNU_SOURCE
.SH DESCRIPTION
.BR utimensat ()
and
.BR futimens ()
update the timestamps of a file with nanosecond precision.
This contrasts with the historical
.BR utime (2)
and
.BR utimes (2),
which permit only second and microsecond precision, respectively,
when setting file timestamps.

With
.BR utimensat ()
the file is specified via the pathname given in
.IR pathname .
With
.BR futimens ()
the file whose timestamps are to be updated is specified via
an open file descriptor,
.IR fd .

For both calls, the new file timestamps are specified in the array
.IR times :
.IR times [0]
specifies the new "last access time" (\fIatime\fP);
.IR times [1]
specifies the new "last modification time" (\fImtime\fP).
Each of the elements of
.I times
specifies a time in seconds and nanoseconds
since the Epoch (00:00:00, 1 Jan 1970, UTC),
in a structure of the following form:
.in +4n
.nf

struct timespec {
    time_t tv_sec;        /* seconds */
    long   tv_nsec;       /* nanoseconds */
};
.fi
.in
.PP
Updated file timestamps are set to the greatest value
supported by the file system that is not greater than the specified time.

If the
.I tv_nsec
field of one of the
.I timespec
structures has the special value
.BR UTIME_NOW ,
then the corresponding file timestamp is set to the current time.
If the
.I tv_nsec
field of one of the
.I timespec
structures has the special value
.BR UTIME_OMIT ,
then the corresponding file timestamp is left unchanged.
In both of these cases, the value of the corresponding
.I tv_sec
.\" 2.6.22 was broken: it is not ignored
field is ignored.

If
.I times
is NULL, then both timestamps are set to the current time.
.\"
.SS Permissions requirements
To set both file timestamps to the current time (i.e.,
.I times
is NULL, or both
.I tv_nsec
fields specify
.BR UTIME_NOW ),
either:
.IP 1. 3
the caller must have write access to the file;
.\" 2.6.22 was broken here -- for futimens() the check is
.\" based on whether or not the file descriptor is writable,
.\" not on whether the the caller's effective UID has write
.\" permission for the file referred to by the descriptor.
.IP 2.
the caller's effective user ID must match the owner of the file; or
.IP 3.
the caller must have appropriate privileges.
.PP
To make any change other than setting both timestamps to the
current time (i.e.,
.I times
is not NULL, and both
.I tv_nsec
fields are not
.B UTIME_NOW
.\" 2.6.22 was broken here:
.\" both must something other than *either* UTIME_OMIT *or* UTIME_NOW.
and both
.I tv_nsec
fields are not
.BR UTIME_OMIT ),
either condition 2 or 3 above must apply.

If both
.I tv_nsec
fields are specified as
.BR UTIME_OMIT ,
then no file ownership or permission checks are performed,
and the file timestamps are not modified,
but other error conditions may still be detected.
.\"
.\"
.SS utimensat() specifics
If
.I pathname
is relative, then by default it is interpreted relative to the
directory referred to by the open file descriptor,
.IR dirfd
(rather than relative to the current working directory of
the calling process, as is done by
.BR utimes (2)
for a relative pathname).
See
.BR openat (2)
for an explanation of why this can be useful.
.\" FIXME . Say something about O_SEARCH?  (But it's not in current
.\" glibc (Mar 08), or kernel 2.6.25.)

If
.I pathname
is relative and
.I dirfd
is the special value
.BR AT_FDCWD ,
then
.I pathname
is interpreted relative to the current working
directory of the calling process (like
.BR utimes (2)).

If
.I pathname
is absolute, then
.I dirfd
is ignored.

The
.I flags
field is a bit mask that may be 0, or include the following constant,
defined in
.IR <fcntl.h> :
.TP
.B AT_SYMLINK_NOFOLLOW
If
.I pathname
specifies a symbolic link, then update the timestamps of the link,
rather than the file to which it refers.
.SH "RETURN VALUE"
On success,
.BR utimensat ()
and
.BR futimens ()
return 0.
On error, \-1 is returned and
.I errno
is set to indicate the error.
.SH ERRORS
.TP
.B EACCES
.I times
is NULL,
or both
.I tv_nsec
values are
.BR UTIME_NOW ,
and:
.PD 0
.RS
.IP * 2