utime(2)utime(2)NAME
utime, utimes - Set file access and modification times
SYNOPSIS
#include <sys/time.h> #include <utime.h> #include <sys/types.h>
int utime(
const char *path,
const struct utimbuf *times ); int utimes(
const char *path,
const struct timeval times[2] );
The following definitions of the utime() and utimes() functions do not
conform to current standards and are supported only for backward com‐
patibility. int utime(
const char *path,
struct utimbuf *times ); int utimes(
const char *path,
struct timeval times[2] );
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
utime(): XSH4.0, XSH4.2, XSH5.0
utimes(): XSH4.2, XSH5.0
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
PARAMETERS
Points to the file. If the final component of the path parameter names
a symbolic link, the link will be traversed and pathname resolution
will continue. Points to a utimbuf structure for the utime() function,
or to an array of timeval structures for the utimes() function.
DESCRIPTION
The utimes() function sets the access and modification times of the
file pointed to by the path parameter to the value of the times parame‐
ter. The utimes() function allows time specifications accurate to the
microsecond.
The utime() function also sets file access and modification times; how‐
ever, each time is contained in a single integer and is accurate only
to the nearest second.
For utime(), the times parameter is a pointer to a utimbuf structure,
defined in the <utime.h> header file. The first structure member repre‐
sents the date and time of last access, and the second member repre‐
sents the date and time of last modification. The times in the utimbuf
structure are measured in seconds since the epoch (00:00:00, January 1,
1970, Coordinated Universal Time (UTC)).
For utimes(), the times parameter is an array of timeval structures, as
defined in the <sys/time.h> header file. The first array element repre‐
sents the date and time of last access, and the second element repre‐
sents the date and time of last modification. The times in the timeval
structure are measured in seconds and microseconds since the epoch,
although rounding toward the nearest second may occur.
If the times parameter is null, the access and modification times of
the file are set to the current time. If the file is a remote file, the
current time at the remote node, rather than the local node, is used.
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 privilege
in order to use the call in this manner.
If the times parameter is not null, the access and modification times
are set to the values contained in the designated structure, regardless
of whether those times correlate with the current time. Only the owner
of the file or a user with superuser privilege can use the call this
way.
Upon successful completion, the utime() and utimes() functions mark the
time of the last file status change, st_ctime, for update.
NOTES
The utime() and utimes() functions are not recommended for operations,
such as backing up or archiving files, that need to change a file's
atime (access time) or mtime (modification time) but not change the
file's ctime (attribute change time). For such operations, use the
fcntl() function's F_GETTIMES and F_SETTIMES requests. See fcntl(2) for
more information.
RETURN VALUES
Upon successful completion, a value of 0 (zero) is returned. Otherwise,
a value of -1 is returned, errno is set to indicate the error, and the
file times will not be affected.
ERRORS
If the utimes() or utime() function fails, errno may be set to one of
the following values: Search permission is denied by a component of the
path prefix; or the times parameter is null and the effective user ID
is neither the owner of the file nor has appropriate system privilege,
and write access is denied. [Tru64 UNIX] The path parameter is an
invalid address, or (for utimes()) either the path or times parameter
is an invalid address. [Tru64 UNIX] The file is not a regular file.
Too many links were encountered in translating path. The length of the
path parameter exceeds PATH_MAX, or a pathname component is longer than
NAME_MAX, or pathname resolution of a symbolic link produced an inter‐
mediate result whose length exceeds PATH_MAX. The named file does not
exist or the path parameter points to an empty string. A component of
the path prefix is not a directory. The times parameter is not the
null value and the calling process has write access to the file but
neither owns the file nor has the appropriate system privilege. The
file system that contains the file is mounted read-only. [Tru64
UNIX] The process' root or current directory is located in a virtual
file system that has been unmounted.
The utimes() function can also fail if additional errors occur.
SEE ALSO
Functions: fcntl(2), stat(2)
Standards: standards(5)utime(2)