Standards
| Standards / Extensions |
C or C++ |
Dependencies |
|---|
XPG4.2
Single UNIX Specification, Version 3
|
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.