utimes()

Updated: April 19, 2023

Set a file's access and modification times

Synopsis:

#include <sys/time.h>

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

Arguments:

path
The name of the file whose times you want to set.
times
NULL, or an array of timeval structures:
  • The first array member represents the date and time of last access.
  • The second member represents the date and time of last modification.

Library:

libc

Use the -l c option to qcc to link against this library. This library is usually included automatically.

Description:

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

The times in the timeval structure are measured in seconds and microseconds since the Unix Epoch (00:00:00 January 1, 1970 Coordinated Universal Time (UTC)), although rounding toward the nearest second may occur.

If the times argument is NULL, 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 superuser privileges to use this call in this manner. On completion, utimes() marks the time of the last file status change, st_ctime, for update.

Returns:

0
Success.
-1
An error occurred (errno is set).

Errors:

EACCES
Search permission is denied by a component of the path prefix, or the times argument is NULL and the effective user ID of the process doesn't match the owner of the file and write access is denied.
EFAULT
The path or times argument points to an illegal address.
EINTR
A signal was caught during 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 filesystem.
ELOOP
Too many symbolic links were encountered in resolving path.
EMULTIHOP
Components of path require hopping to multiple remote machines and the filesystem doesn't allow it.
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 doesn't name an existing file, or path is an empty string.
ENOTDIR
A component of the path prefix isn't a directory.
EPERM
The times argument isn't NULL and the calling process's effective user ID has write access to the file but doesn't match the owner of the file, and the calling process doesn't have the appropriate privileges.
EROFS
The filesystem containing the file is read-only.
ENAMETOOLONG
Path name resolution of a symbolic link produced an intermediate result whose length exceeds PATH_MAX.

Classification:

POSIX 1003.1 XSI

Safety:  
Cancellation point No
Interrupt handler No
Signal handler Yes
Thread Yes