155 lines
3.7 KiB
Groff
155 lines
3.7 KiB
Groff
'\"macro stdmacro
|
|
.if n .pH g2.utime @(#)utime 41.4 of 5/26/91
|
|
.\" Copyright 1991 UNIX System Laboratories, Inc.
|
|
.\" Copyright 1989, 1990 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
|
|
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\fP
|
|
Write permission on the file named by \f2path\fP is denied.
|
|
.TP
|
|
\f4EACCES\f1
|
|
The effective user ID is
|
|
not the owner of the file, \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 calling process does not have the super-user privilege, the
|
|
effective user ID is
|
|
not the owner of the file, and \f2times\f1 is not \f4NULL\f1.
|
|
.TP
|
|
\f4EPERM\fP
|
|
The calling process does not have the super-user privilege, the
|
|
effective user ID is
|
|
not the owner of the file, \f2times\f1 is \f4NULL\f1,
|
|
and write permission on the file named by \f2path\fP is denied.
|
|
.TP
|
|
\f4EROFS\f1
|
|
The file system containing the file is mounted read-only.
|
|
.TP
|
|
\f4EROFS\f1
|
|
The current file system level range does not envelop the level of the
|
|
file named by \f2path\fP, and the calling process does not have the
|
|
super-user privilege.
|
|
.TP
|
|
\f4ENOSYS\f1
|
|
When the named file cannot have its time reset. The file is on a
|
|
file system that doesn't have this operation. Example, the /dev/fd/0
|
|
file is on a file system that doesn't allow the time to be reset.
|
|
.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.
|