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

See also:

stat()