utime, utimes - Set file access and modification times
#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 compatibility. int utime(
const char *path,
struct utimbuf *times ); int utimes(
const char *path,
struct timeval times[2] );
Interfaces documented on this reference page conform to
industry standards 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.
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.
The utimes() function sets the access and modification
times of the file pointed to by the path parameter to the
value of the times parameter. The utimes() function allows
time specifications accurate to the microsecond.
The utime() function also sets file access and modification
times; however, 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 represents the date and time of last
access, and the second member represents 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 represents the date and time of
last access, and the second element represents 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.
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.
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.
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 intermediate 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.
Functions: fcntl(2), stat(2)
Standards: standards(5)
utime(2)
[ Back ] |
