utimes() — Set file access and modification times
Standards
Standards / Extensions | C or C++ | Dependencies |
---|---|---|
XPG4.2 |
both |
Format
#define _XOPEN_SOURCE_EXTENDED 1
#include <sys/time.h>
int utimes(const char *path, const struct timeval times[2]);
General 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 times argument
is an array of two timeval structures. The first
array member represents the date and time of the last access, and
the second member represents the date and time of the last modification.
The times in the timeval structure are measured
in seconds and microseconds since the Epoch, but the actual time stored
with the file are rounded to the nearest second. The timeval members
are:
- tv_sec
- seconds since January 1, 1970 (UTC)
- tv_usec
- microseconds
If the times argument is a NULL pointer, the access and modification times of the file are set to the current time. The same process privilege requirements of the utime() function are required by utimes(). The last file status change, field st_ctime in a stat(), is updated with the current time.
Note: The utimes() function
has been moved to the Legacy Option group in Single UNIX Specification, Version 3 and may be withdrawn
in a future version. The utime() function is preferred for portability.
Returned value
If successful, utimes() returns 0.
If unsuccessful, utimes() returns -1 and sets errno
to one of the following values:
- Error Code
- Description
- EACCES
- The process does not have search permission on some component
of the path prefix; or all of the following
are true:
- times is NULL
- The effective user ID of the process does not match the file's owner
- The process does not have write permission on the file
- The process does not have appropriate privileges
- ELOOP
- A loop exists in symbolic links. This error is issued if more than POSIX_SYMLOOP symbolic links (defined in the limits.h header file) are detected in the resolution of path.
- ENAMETOOLONG
- path is longer than PATH_MAX characters or some component of path is longer than NAME_MAX characters while _POSIX_NO_TRUNC is in effect. For symbolic links, the length of the pathname string substituted for a symbolic link exceeds PATH_MAX. The PATH_MAX and NAME_MAX values can be determined using pathconf().
- ENOTDIR
- Some component of the path prefix is not a directory.
- ENOTENT
- There is no file named path, or the path argument is an empty string.
- EPERM
- times is not NULL, the effective user ID of the calling process does not match the owner of the file, and the calling process does not have appropriate privileges.
- EROFS
- path is on a read-only file system.