futimesat(2)

NAME

     utimes, futimesat - set file access and modification times

SYNOPSIS

     #include <sys/time.h>

     int utimes(const char *path, const struct timeval times[2]);

     int futimesat(int fildes, const  char  *path,  const  struct
     timeval times[2]);

DESCRIPTION

     The utimes() function sets the access and modification times
     of  the file pointed to by the path argument to the value of
     the times argument. It allows time  specifications  accurate
     to the microsecond.

     The futimesat() function also sets access  and  modification
     times.  See fsattr(5). If path is a relative path name, how-
     ever, futimesat() resolves the path relative to  the  fildes
     argument  rather  than  the  current  working directory.  If
     fildes is set to AT_FDCWD, defined in <fcntl.h>, futimesat()
     resolves the path relative to the current working directory.
     If path is a null pointer, futimesat() sets the  access  and
     modification  times  on  the  file referenced by fildes. The
     fildes argument is ignored even when futimesat() is provided
     with an absolute path.

     The times argument is an array of  timeval  structures.  The
     first  array  member  represents  the  date and time of last
     access, and the second member represents the date  and  time
     of  last  modification.   The times in the timeval structure
     are measured in seconds and microseconds  since  the  Epoch,
     although rounding toward the nearest second may occur.

     If the times argument is a  null  pointer,  the  access  and
     modification  times of the file are set to the current time.
     The effective user ID of the process must be the same as the
     owner  of the file, or must have write access to the file or
     super-user privileges to use this call in this manner.  Upon
     completion,  utimes()  will  mark  the time of the last file
     status change, st_ctime, for update.

RETURN VALUES

     Upon successful completion, 0 is returned.  Otherwise, -1 is
     returned,  errno  is set to indicate the error, and the file
     times will not be affected.

ERRORS

     The utimes() and futimesat() functions will fail if:

     EACCES
           Search permission is denied by a component of the path
           prefix;  or  the  times argument is a null pointer and
           the effective user ID of the process  does  not  match
           the owner of the file and write access is denied.

     EFAULT
           The path  or  times  argument  points  to  an  illegal
           address.  For  futimesat(),  path might have the value
           NULL if the fildes argument refers  to  a  valid  open
           file descriptor.

     EINTR A signal  was  caught  during  the  execution  of  the
           utimes() function.

     EINVAL
           The number of microseconds specified in one or both of
           the timeval structures pointed to by times was greater
           than or equal to 1,000,000 or less than 0.

     EIO   An I/O error occurred while reading from or writing to
           the file system.

     ELOOP Too many symbolic links were encountered in  resolving
           path.

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

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

     ENOENT
           A component of path does not name an existing file  or
           path is an empty string.

     ENOTDIR
           A component of the path prefix is not a  directory  or
           the  path argument is relative and the fildes argument
           is not AT_FDCWD or does not refer to  a  valid  direc-
           tory.

     EPERM The times argument is not a null pointer and the  cal-
           ling  process's  effective user ID has write access to
           the file but does not match the owner of the file  and
           the  calling  process  does  not  have the appropriate
           privileges.

     EROFS The file system containing the file is read-only.

     The utimes() and futimesat() functions may fail if:

     ENAMETOOLONG
           Path name resolution of a symbolic  link  produced  an
           intermediate result whose length exceeds {PATH_MAX}.

ATTRIBUTES

     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
   |        ATTRIBUTE TYPE       |        ATTRIBUTE VALUE      |
   | ____________________________|_____________________________|_
   |  Interface Stability        |  utimes() is Standard;  fun-|
   |                             |  timesat() is Evolving      |
   |_____________________________|_____________________________|

SEE ALSO

     stat(2), attributes(5), fsattr(5)