# utime

## NAME



           utime, utimes - change file last access and modification times
    


## LIBRARY



           Standard C library (_libc_ , _-lc_)
    


## SYNOPSIS



           **#include <utime.h>**
    
           **int utime(const char ***_path_**,**
                     **const struct utimbuf *_Nullable** _times_**);**
    
           **#include <sys/time.h>**
    
           **int utimes(const char ***_path_**,**
                     **const struct timeval** _times_**[_Nullable 2]);**
    


## DESCRIPTION



           **Note:** modern applications may prefer to use the interfaces
           described in utimensat(2).
    
           The **utime**() system call changes the access and modification times
           of the inode specified by _path_ to the _actime_ and _modtime_ fields of
           _times_ respectively.  The status change time (ctime) will be set to
           the current time, even if the other time stamps don't actually
           change.
    
           If _times_ is NULL, then the access and modification times of the
           file are set to the current time.
    
           Changing timestamps is permitted when: either the process has
           appropriate privileges, or the effective user ID equals the user
           ID of the file, or _times_ is NULL and the process has write
           permission for the file.
    
           The _utimbuf_ structure is:
    
               struct utimbuf {
                   time_t actime;       /* access time */
                   time_t modtime;      /* modification time */
               };
    
           The **utime**() system call allows specification of timestamps with a
           resolution of 1 second.
    
           The **utimes**() system call is similar, but the _times_ argument refers
           to an array rather than a structure.  The elements of this array
           are _timeval_ structures, which allow a precision of 1 microsecond
           for specifying timestamps.  The _timeval_ structure is:
    
               struct timeval {
                   long tv_sec;        /* seconds */
                   long tv_usec;       /* microseconds */
               };
    
           _times[0]_ specifies the new access time, and _times[1]_ specifies the
           new modification time.  If _times_ is NULL, then analogously to
           **utime**(), the access and modification times of the file are set to
           the current time.
    


## RETURN VALUE



           On success, zero is returned.  On error, -1 is returned, and _errno_
           is set to indicate the error.
    


## ERRORS



           **EACCES** Search permission is denied for one of the directories in
                  the path prefix of _path_ (see also path_resolution(7)).
    
           **EACCES** _times_ is NULL, the caller's effective user ID 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_DAC_OVERRIDE** or the
                  **CAP_FOWNER** capability).
    
           **EFAULT** _path_ points to an invalid address.
    
           **ENOENT** _path_ does not exist.
    
           **EPERM** _times_ is not NULL, the caller's effective UID does not
                  match the owner of the file, and the caller is not
                  privileged (Linux: does not have the **CAP_FOWNER**
                  capability).
    
           **EROFS** _path_ resides on a read-only filesystem.
    


## STANDARDS



           POSIX.1-2008.
    


## NOTES



           Linux does not allow changing the timestamps on an immutable file,
           or setting the timestamps to something other than the current time
           on an append-only file.
    


* * *