2:utime

From Linux Man Pages

      utime, utimes - change access and/or modification times of an inode
      

Contents 1 SYNOPSIS 2 DESCRIPTION 3 RETURN VALUE 4 ERRORS 5 NOTES 6 BUGS 7 CONFORMING TO 8 RELATED 9 CATEGORY

SYNOPSIS

      #include <sys/types.h>
      #include <utime.h>
 
      int utime(const char *filename, const struct utimbuf *buf);
 
      #include <sys/time.h>
 
      int utimes(const char *filename, const struct timeval times[2]);

DESCRIPTION

      utime()  changes  the  access and modification times of the inode specified by filename to the actime and modtime
      fields of buf respectively.
 
      If buf is NULL, then the access and modification times of the file are set to the current time.
 
      Changing time stamps is permitted when: either the process has appropriate privileges (Linux: has the  CAP_FOWNER
      capability),  or  the  effective  user ID equals the user ID of the file, or buf must is NULL and the process has
      write permission to the file.
 
      The utimbuf structure is:
 
             struct utimbuf {
                 time_t actime;       /* access time */
                 time_t modtime;      /* modification time */
             };
 
      The function utime() allows specification of time stamps with a resolution of 1 second.  The function utimes() is
      similar,  but allows a resolution of 1 microsecond.  Here times[0] refers to access time, and times[1] to modifi-
      cation time.
 
      The timeval structure is:
 
             struct timeval {
                 long tv_sec;        /* seconds */
                 long tv_usec;       /* microseconds */
             };

RETURN VALUE

      On success, zero is returned.  On error, -1 is returned, and errno is set appropriately.

ERRORS

      EACCES Search permission is denied for one of the directories in the path prefix of path (see  also  path_resolu-
             tion(2)), or buf is NULL and the process does not have permission to change the time stamps (see above).
 
      ENOENT filename does not exist.
 
      EPERM  buf is not NULL and the process does not have permission to change the time stamps.
 
      EROFS  path resides on a read-only file system.

NOTES

      Linux does not allow changing the time stamps on an immutable file, or setting the time stamps to something other
      than the current time on an append-only file.
 
      In libc4 and libc5, utimes() is just a wrapper for utime() and hence does not allow a subsecond resolution.
 
      POSIX.1-2001 marks utimes() legacy, which is strange since it provides more functionality than utime().

BUGS

      Linux is not careful to distinguish between the EACCES and EPERM error returns.  On the other hand,  POSIX.1-2001
      is buggy in its error description for utimes().

CONFORMING TO

      utime(): SVr4, POSIX.1-2001.
      utimes(): 4.3BSD

RELATED

      chattr(1), futimesat(2), stat(2), futimes(3)

CATEGORY