utimes()

Set a file's access and modification times

Synopsis:

#include <sys/time.h>

int utimes( const char * __path,
            const struct timeval * __times );

Arguments:

__path
The name of the files 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 pointed to 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

Last modified: 2013-12-23

comments powered by Disqus