utimes(S)
utimes --
set file access and modification times
Synopsis
#include <sys/time.h>
int utimes(const char *path, const struct timeval times[2]);
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 utimes function allows time specifications accurate to the
microsecond.
The times argument is an array of two timeval structures.
The first array 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 timeval structure are measured in seconds
and microseconds since the epoch, although rounding toward the nearest
second may occur.
If times is NULL,
the access and modification times of the file are set to the current time.
The effective user ID of the calling process must be
the owner ID of the file or must have write permission on the file,
or the calling process must have the P_OWNER privilege, to
set the file times this way.
If times is not NULL, times is
interpreted as a pointer to a timeval structure (defined
in time.h) and the access and modification times are set
to the values contained in the designated structure.
The effective user ID of the calling process must be the owner
ID of the file or the calling process must have the
P_OWNER privilege to set the file times this way.
Upon completion, utimes will mark the time of the last file
status change, st_ctime
, for update.
Return values
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned,
errno is set to indicate the error,
and file times will not be affected.
Errors
utimes
will fail if one or more of the following are true:
ENOTDIR-
A component of the path prefix of
file
is not a directory.
ENAMETOOLONG-
Pathname resolution of a symbolic link produced an intermediate
result whose length exceeds PATH_MAX; the length of the
path argument exceeds PATH_MAX; or, a pathname component
is longer than NAME_MAX (see
limits(F)).
ENOENT-
A component of path does not name an existing file or
path is an empty string.
EACCES-
Search permission is denied by a component of the path prefix; or
the times argument is a NULL pointer and the effective
user ID of the process does not match the owner of the file and write
access is denied.
ELOOP-
Too many symbolic links were encountered in translating path.
EPERM-
The times argument is not a NULL pointer and the
calling process' effective user ID has write access to the file, but
does not match the owner of the file and the calling process does not
have appropriate privilege.
EACCES-
The effective user ID
of the process is not privileged user and not the owner of the file, write
permission is denied for the file, and times is NULL.
EROFS-
The file system containing the file is mounted read-only.
EFAULT-
The supplied path argument
points outside the process's allocated address space.
Note that an invalid times argument produces a segmentation
fault, and not an error.
References
stat(S),
utime(S)
Notices
utimes is a library routine that calls the
utime(S)
system call.
Standards conformance
This routine conforms to X/Open System Interfaces and Headers,
Issue 4, Version 2.
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 - 01 June 2005