utimes(3C)

utimes -- set file access and modification times

Synopsis

   #include <sys/time.h>
   
   int utimes(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. The utimes function allows time specifications accurate to the microsecond.

The times argument is an array of two 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 times is NULL, the access and modification times of the file are set to the current time. The effective user ID of the calling process must be the owner ID of the file or must have write permission on the file, or the calling process must have the P_OWNER privilege, to set the file times this way.

If times is not NULL, times is interpreted as a pointer to a timeval structure (defined in time.h) and the access and modification times are set to the values contained in the designated structure. The effective user ID of the calling process must be the owner ID of the file or the calling process must have the P_OWNER privilege to set the file times this way.

Upon completion, utimes will mark the time of the last file status change, st_ctime, for update.

Return values

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

Errors

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

ENOTDIR: A component of the path prefix of file is not a directory.
ENAMETOOLONG: Pathname resolution of a symbolic link produced an intermediate result whose length exceeds PATH_MAX; the length of the path argument exceeds PATH_MAX; or, a pathname component is longer than NAME_MAX (see limits(4)).
ENOENT: A component of path does not name an existing file or path is an empty string.
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.
ELOOP: Too many symbolic links were encountered in translating path.
EPERM: The times argument is not a NULL pointer and the calling process' 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 appropriate privilege.
EACCES: The effective user ID of the process is not privileged user and not the owner of the file, write permission is denied for the file, and times is NULL.
EROFS: The file system containing the file is mounted read-only.
EFAULT: The supplied path argument points outside the process's allocated address space.

Note that an invalid times argument produces a segmentation fault, and not an error.

References

stat(2), utime(2)

Notices

utimes is a library routine that calls the utime(2) system call.

Standards conformance

This routine conforms to X/Open System Interfaces and Headers, Issue 4, Version 2.