'\"macro stdmacroME
.if n .pH g2.utime @(#)utime	40.19 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} utime 2 "" "\&"
.if \nX=1 .ds x} utime 2 ""
.if \nX=2 .ds x} utime 2 "" "\&"
.if \nX=3 .ds x} utime "" "" "\&"
.TH \*(x}
.SH NAME
\f4utime\f1 \- set file access and modification times
.SH SYNOPSIS
\f4#include <sys/types.h>\f1
.br
\f4#include <utime.h>\f1
.PP
\f4int utime(const char \(**path, const struct utimbuf \(**times);  \f1
.SH DESCRIPTION
\f2path\f1
points to a
path name
naming a file.
\f4utime\f1
sets the access and modification times
of the named file.
.PP
If
\f2times\f1
is
\f4NULL\f1,
the access and modification times of the file are set to the current time.
A process must be the owner of the file or have write permission to use
\f4utime\f1
in this manner.
.PP
If
\f2times\f1
is not
\f4NULL,\f1
\f2times\f1
is interpreted as a pointer to a
\f4utimbuf\f1
structure (defined in \f4utime.h\f1) and
the access and modification times are set to the values contained in
the designated structure.
Only the owner of the file or the super-user may use
\f4utime\f1
this way.
.PP
The times in the following structure are measured in seconds since
00:00:00
UTC\*S,
Jan. 1, 1970.
.PP
.RS
.ft 4
.nf
.ta .5i 1i 1.75i 2.5i
struct	utimbuf	{
	time_t	actime;	/\(** access time \(**/
	time_t	modtime;	/\(** modification time \(**/
};
.fi
.ft 1
.RE
.PP
\f4utime\f1 also causes the time of the last file status change (\f4st_ctime\f1)
to be updated.
.PP
\f4utime\f1
will fail if one or more of the following are true:
.TP 20
\f4EACCES\f1
Search permission is denied by a component of the
\f2path\f1
prefix.
.TP
\f4EACCES\f1
The effective user ID
is not super-user and not the owner of the file
and 
\f2times\f1
is
\f4NULL\f1
and write access is denied.
.TP 20
\f4EFAULT\f1
\f2times\f1
is not
\f4NULL\f1
and points outside the process's allocated address space.
.TP 20
\f4EFAULT\f1
\f2path\f1
points outside the process's allocated address space.
.TP 20
\f4EINTR\f1
A signal was caught during the \f4utime\f1 system call.
.TP
\f4ELOOP\f1
Too many symbolic links were encountered in translating \f2path\f1.
.TP
\f4EMULTIHOP\f1
Components of \f2path\f1 require hopping to multiple
remote machines
and the file system does not allow it.
.TP 20
\f4ENAMETOOLONG\f1
The length of the \f2path\f1 argument exceeds {\f4PATH_MAX\f1}, or the
length of a \f2path\f1 component exceeds {\f4NAME_MAX\f1} while
\f4_POSIX_NO_TRUNC\f1 is in effect.
.TP 20
\f4ENOENT\f1
The named file does not exist or is a null pathname.
.TP 20
\f4ENOLINK\f1
\f2path\f1 points to a remote machine and the link
to that machine is no longer active.
.TP 20
\f4ENOTDIR\f1
A component of the
\f2path\f1
prefix
is not a directory.
.TP 20
\f4EPERM\f1
The effective user ID
is not super-user and not the owner of the file
and
\f2times\f1
is not
\f4NULL\f1.
.TP
\f4EROFS\f1
The file system containing the file is mounted read-only.
.SH "SEE ALSO"
\f4stat\f1(2).
.SH "DIAGNOSTICS"
Upon successful completion, a value of 0 is returned.
Otherwise, a value of \-1 is returned and
\f4errno\f1
is set to indicate the error.
