utime
Purpose
Sets file access and modification times.
Syntax
#include <unistd.h>
int utime (path, times)
char *path;
struct utimbuf *times;
Description
The utime system call sets the access and modification
times of the file pointed to by the path parameter to the
value of the times parameter. If Distributed Services is
installed on your system, this path can cross into
another node.
If the times parameter is NULL, the access and modifica-
tion 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 permission in order to use
the utime system call in this manner.
If the times parameter is not NULL, it is a pointer to a
utimbuf structure and the access and modification times
are set to the values contained in the designated struc-
ture, regardless of whether or not those times correlate
with the current time. For remote files, if the utime
system call is used in this way, the file's times may be
different from the time at the remote node. Only the
owner of the file or superuser can use the utime system
call this way.
The utimbuf structure pointed to by the times parameter
is defined in the unistd.h file, and it contains the fol-
lowing members.
time_t actime; /* Date and time of last access */
time_t modtime; /* Date and time of last modification */
The times in this structure are measured in seconds since
00:00:00 GMT, January 1, 1970.
Return Value
Upon successful completion, a value of 0 is returned. If
the utime system call fails, a value of -1 is returned
and errno is set to indicate the error.
Diagnostics
The utime system call fails if one or more of the fol-
lowing are true:
ENOENT The named file does not exist.
ENOTDIR A component of the path prefix is not a direc-
tory.
EACCES Search permission is denied by a component of
the path prefix.
EPERM The effective user ID is not superuser or the
owner of the file and the times parameter is
not NULL.
EACCES The effective user ID is not superuser or the
owner of the file, the times parameter is
NULL, and write access is denied.
EROFS The file system containing the file is mounted
read-only.
EFAULT The times or path parameter &pointsout..
ESTALE The process's root or current directory is
located in a virtual file system that has been
unmounted.
If Distributed Services is installed on your system,
utime can also fail if one or more of the following are
true:
EDIST The server has blocked new inbound
requests.
EDIST Outbound requests are currently blocked.
EDIST The server has a release level of Distrib-
uted Services that cannot communicate with
this node.
EAGAIN The server is too busy to accept the
request.
ESTALE The file descriptor for a remote file has
become obsolete.
EPERM The translate tables of the server did not
contain any entry for either the effective
user ID or effective group ID of the
calling process.
ENODEV The named file is a remote file located on
a device that has been unmounted at the
server.
ENOMEM Either this node or the server does not
have enough memory available to service the
request.
ENOCONNECT An attempt to establish a new network con-
nection with a remote node failed.
EBADCONNECT An attempt to use an existing network con-
nection with a remote node failed.
Related Information
In this book: "stat, fstat."