UTIME(2)                             SysV                             UTIME(2)



NAME
     utime - set file access and modification times

SYNOPSIS
     #include <sys/types.h>

     int utime (path, times)
     char *path;
     struct utimbuf *times;

DESCRIPTION
     path points to a pathname naming a file.  If the final component names a
     symbolic link, the link is traversed and path resolution continues.
     utime sets the access and modification times of the named file.

     If times is NULL, the access and modification times of the file are set
     to the current time.  A process must be the owner of the file or have
     write permission to use utime in this manner.

     If times is not NULL, times is interpreted as a pointer to a utimbuf
     structure and the access and modification times are set to the values
     contained in the designated structure.  Only the owner of the file or the
     super-user may use utime this way.

     The times in the following structure are measured in seconds since
     midnight (00:00) on 1 January 1970 UTC.  ("UTC" is an abbreviation for
     "Coordinated Universal Time," which is just another, less parochial, term
     for Greenwich Mean Time or "GMT.")

          struct utimbuf {
                 time_t  actime;   /* access time */
                 time_t  modtime;  /* modification time */
          };

     Upon successful completion, the utime function marks the time of the last
     file status change, st_ctime, for update.

DIAGNOSTICS
     Upon successful completion, a value of 0 is returned.  Otherwise, a value
     of -1 is returned and errno is set to indicate the error.

ERRORS
     utime will fail if one or more of the following are true:

     [ENOENT]      The named file does not exist; or path points to an empty
                   directory.

     [ENOTDIR]     A component of the path prefix is not a directory.

     [EACCES]      Search permission is denied by a component of the path
                   prefix.

     [EPERM]       The effective user ID is not super-user and not the owner
                   of the file and times is not NULL.

     [EACCES]      The effective user ID is not super-user and not the owner
                   of the file and times is NULL and write access is denied.

     [EROFS]       The file system containing the file is mounted read-only.

     [EFAULT]      times is not NULL and points outside the process' allocated

                   address space.

     [EFAULT]      path points outside the process' allocated address space.

     [EINTR]       A signal was caught during the utime system call.

     [ENAMETOOLONG]
                   The length of the path argument exceeds PATH_MAX or a
                   pathname component is longer than NAME_MAX.

NOTES
     Under other implementations, utime fails if either of the following is
     true:

     [ENOLINK]     path points to a remote machine and the link to that
                   machine is no longer active.

     [EMULTIHOP]   Components of path require hopping to multiple remote
                   machines.


SEE ALSO
     stat(2).