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 |