# utimensat

## NAME



           utimensat, futimens - change file timestamps with nanosecond
           precision
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <fcntl.h>            **/* Definition of **AT_*** constants */
           **#include <sys/stat.h>**
    
           **int utimensat(int** _dirfd_**, const char ***_path_**,**
                         **const struct timespec** _times_**[_Nullable 2], int** _flags_**);**
           **int futimens(int** _fd_**, const struct timespec** _times_**[_Nullable 2]);**
    
       Feature Test Macro Requirements for glibc (see
       feature_test_macros(7)):
    
           **utimensat**():
               Since glibc 2.10:
                   _POSIX_C_SOURCE >= 200809L
               Before glibc 2.10:
                   _ATFILE_SOURCE
    
           **futimens**():
               Since glibc 2.10:
                   _POSIX_C_SOURCE >= 200809L
               Before glibc 2.10:
                   _GNU_SOURCE
    


## DESCRIPTION



           **utimensat**() and **futimens**() update the timestamps of a file with
           nanosecond precision.  This contrasts with the historical utime(2)
           and utimes(2), which permit only second and microsecond precision,
           respectively, when setting file timestamps.
    
           With **utimensat**() the file is specified via the pathname given in
           _path_.  With **futimens**() the file whose timestamps are to be updated
           is specified via an open file descriptor, _fd_.
    
           For both calls, the new file timestamps are specified in the array
           _times_ : _times[0]_ specifies the new "last access time" (_atime_);
           _times[1]_ specifies the new "last modification time" (_mtime_).  Each
           of the elements of _times_ specifies a time as the number of seconds
           and nanoseconds since the Epoch, 1970-01-01 00:00:00 +0000 (UTC).
           This information is conveyed in a **timespec**(3) structure.
    
           Updated file timestamps are set to the greatest value supported by
           the filesystem that is not greater than the specified time.
    
           If the _tv_nsec_ field of one of the _timespec_ structures has the
           special value **UTIME_NOW** , then the corresponding file timestamp is
           set to the current time.  If the _tv_nsec_ field of one of the
           _timespec_ structures has the special value **UTIME_OMIT** , then the
           corresponding file timestamp is left unchanged.  In both of these
           cases, the value of the corresponding _tv_sec_ field is ignored.
    
           If _times_ is NULL, then both timestamps are set to the current
           time.
    
           The status change time (ctime) will be set to the current time,
           even if the other time stamps don't actually change.
    
       **Permissions requirements**
           To set both file timestamps to the current time (i.e., _times_ is
           NULL, or both _tv_nsec_ fields specify **UTIME_NOW**), either:
    
           •  the caller must have write access to the file;
    
           •  the caller's effective user ID must match the owner of the
              file; or
    
           •  the caller must have appropriate privileges.
    
           To make any change other than setting both timestamps to the
           current time (i.e., _times_ is not NULL, and neither _tv_nsec_ field
           is **UTIME_NOW** and neither _tv_nsec_ field is **UTIME_OMIT**), either
           condition 2 or 3 above must apply.
    
           If both _tv_nsec_ fields are specified as **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.
    
       **utimensat() specifics**
           If _path_ is relative, then by default it is interpreted relative to
           the directory referred to by the open file descriptor, _dirfd_
           (rather than relative to the current working directory of the
           calling process, as is done by utimes(2) for a relative pathname).
           See openat(2) for an explanation of why this can be useful.
    
           If _path_ is relative and _dirfd_ is the special value **AT_FDCWD** , then
           _path_ is interpreted relative to the current working directory of
           the calling process (like utimes(2)).
    
           If _path_ is absolute, then _dirfd_ is ignored.
    
           The _flags_ argument is a bit mask created by ORing together zero or
           more of the following values defined in _< fcntl.h>_:
    
           **AT_EMPTY_PATH**(since Linux 5.8)
                  If _path_ is an empty string, operate on the file referred to
                  by _dirfd_ (which may have been obtained using the open(2)
                  **O_PATH** flag).  In this case, _dirfd_ can refer to any type of
                  file, not just a directory.  If _dirfd_ is **AT_FDCWD** , the call
                  operates on the current working directory.  This flag is
                  Linux-specific; define **_GNU_SOURCE** to obtain its
                  definition.
    
           **AT_SYMLINK_NOFOLLOW**
                  If _path_ specifies a symbolic link, then update the
                  timestamps of the link, rather than the file to which it
                  refers.
    


## RETURN VALUE



           On success, **utimensat**() and **futimens**() return 0.  On error, -1 is
           returned and _errno_ is set to indicate the error.
    


## ERRORS



           **EACCES** _times_ is NULL, or both _tv_nsec_ values are **UTIME_NOW** , and
                  the effective user ID of the caller does not match the
                  owner of the file, the caller does not have write access to
                  the file, and the caller is not privileged (Linux: does not
                  have either the **CAP_FOWNER** or the **CAP_DAC_OVERRIDE**
                  capability).
    
           **EBADF**(**futimens**()) _fd_ is not a valid file descriptor.
    
           **EBADF**(**utimensat**()) _path_ is relative but _dirfd_ is neither
                  **AT_FDCWD** nor a valid file descriptor.
    
           **EFAULT** _times_ pointed to an invalid address; or, _dirfd_ was
                  **AT_FDCWD** , and _path_ is NULL or an invalid address.
    
           **EINVAL** Invalid value in _flags_.
    
           **EINVAL** Invalid value in one of the _tv_nsec_ fields (value outside
                  range [0, 999,999,999], and not **UTIME_NOW** or **UTIME_OMIT**);
                  or an invalid value in one of the _tv_sec_ fields.
    
           **EINVAL** _path_ is NULL, _dirfd_ is not **AT_FDCWD** , and _flags_ contains
                  **AT_SYMLINK_NOFOLLOW**.
    
           **ELOOP**(**utimensat**()) Too many symbolic links were encountered in
                  resolving _path_.
    
           **ENAMETOOLONG**
                  (**utimensat**()) _path_ is too long.
    
           **ENOENT**(**utimensat**()) A component of _path_ does not refer to an
                  existing directory or file, or _path_ is an empty string.
    
           **ENOTDIR**
                  (**utimensat**()) _path_ is relative, but _dirfd_ is neither
                  **AT_FDCWD** nor a file descriptor referring to a directory;
                  or, one of the prefix components of _path_ is not a
                  directory.
    
           **EPERM** The caller attempted to change one or both timestamps to a
                  value other than the current time, or to change one of the
                  timestamps to the current time while leaving the other
                  timestamp unchanged, (i.e., _times_ is not NULL, neither
                  _tv_nsec_ field is **UTIME_NOW** , and neither _tv_nsec_ field is
                  **UTIME_OMIT**) and either:
    
                  •  the caller's effective user ID does not match the owner
                     of file, and the caller is not privileged (Linux: does
                     not have the **CAP_FOWNER** capability); or,
    
                  •  the file is marked append-only or immutable (see
                     chattr(1)).
    
           **EROFS** The file is on a read-only filesystem.
    
           **ESRCH**(**utimensat**()) Search permission is denied for one of the
                  prefix components of _path_.
    


## ATTRIBUTES



           For an explanation of the terms used in this section, see
           attributes(7).
           ┌──────────────────────────────────────┬───────────────┬─────────┐
           │ **Interface** │ **Attribute** │ **Value** │
           ├──────────────────────────────────────┼───────────────┼─────────┤
           │ **utimensat**(), **futimens**()              │ Thread safety │ MT-Safe │
           └──────────────────────────────────────┴───────────────┴─────────┘
    


## VERSIONS



       **C library/kernel ABI differences**
           On Linux, **futimens**() is a library function implemented on top of
           the **utimensat**() system call.  To support this, the Linux
           **utimensat**() system call implements a nonstandard feature: if _path_
           is NULL, then the call modifies the timestamps of the file
           referred to by the file descriptor _dirfd_ (which may refer to any
           type of file).  Using this feature, the call _futimens(fd, times)_
           is implemented as:
    
               utimensat(fd, NULL, times, 0);
    
           Note, however, that the glibc wrapper for **utimensat**() disallows
           passing NULL as the value for _path_ : the wrapper function returns
           the error **EINVAL** in this case.
    


## STANDARDS



           POSIX.1-2008.
    


## VERSIONS



           **utimensat**()
                  Linux 2.6.22, glibc 2.6.  POSIX.1-2008.
    
           **futimens**()
                  glibc 2.6.  POSIX.1-2008.
    


## NOTES



           **utimensat**() obsoletes futimesat(2).
    
           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.  (This is
           consistent with the historical behavior of utime(2) and utimes(2)
           on Linux.)
    
           If both _tv_nsec_ fields are specified as **UTIME_OMIT** , then the Linux
           implementation of **utimensat**() succeeds even if the file referred
           to by _dirfd_ and _path_ does not exist.
    


## BUGS



           Several bugs afflict **utimensat**() and **futimens**() before Linux
           2.6.26.  These bugs are either nonconformances with the POSIX.1
           draft specification or inconsistencies with historical Linux
           behavior.
    
           •  POSIX.1 specifies that if one of the _tv_nsec_ fields has the
              value **UTIME_NOW** or **UTIME_OMIT** , then the value of the
              corresponding _tv_sec_ field should be ignored.  Instead, the
              value of the _tv_sec_ field is required to be 0 (or the error
              **EINVAL** results).
    
           •  Various bugs mean that for the purposes of permission checking,
              the case where both _tv_nsec_ fields are set to **UTIME_NOW** isn't
              always treated the same as specifying _times_ as NULL, and the
              case where one _tv_nsec_ value is **UTIME_NOW** and the other is
              **UTIME_OMIT** isn't treated the same as specifying _times_ as a
              pointer to an array of structures containing arbitrary time
              values.  As a result, in some cases: a) file timestamps can be
              updated by a process that shouldn't have permission to perform
              updates; b) file timestamps can't be updated by a process that
              should have permission to perform updates; and c) the wrong
              _errno_ value is returned in case of an error.
    
           •  POSIX.1 says that a process that has _write access to the file_
              can make a call with _times_ as NULL, or with _times_ pointing to
              an array of structures in which both _tv_nsec_ fields are
              **UTIME_NOW** , in order to update both timestamps to the current
              time.  However, **futimens**() instead checks whether the _access_
              _mode of the file descriptor allows writing_.
    


* * *