NAME
utime() — set file access and modification times
SYNOPSIS
#include <utime.h>
int utime(const char *path, const struct utimbuf *times);
DESCRIPTION
The
utime()
system call sets the access and modification times of the file to which the
path
argument refers.
If
times
is a NULL pointer,
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 on the file to use
utime()
in this manner.
The following times in the
utimbuf
structure defined in
<utime.h>
are measured in seconds since
00:00:00 UTC (Coordinated Universal Time), January 1, 1970.
time_t actime; /* access time */
time_t modtime; /* modification time */
Security Restrictions
If
times
is not a NULL pointer,
times
is interpreted as a pointer to a
utimbuf
structure,
and the access and modification times are set
to the values contained in the designated structure.
Only the owner of the file or
a user with the
OWNER
privilege
can use
utime()
this way.
See
privileges(5)
for more information about privileged access on
systems that support fine-grained privileges.
RETURN VALUE
utime()
returns the following values:
- 0
Successful completion.
- -1
Failure.
errno
is set to indicate the error.
ERRORS
If
utime()
fails,
errno
is set to one of the following values.
- EACCES
Search permission is denied by a component of the path prefix.
- EACCES
The effective user ID is not a
user with the
DAC_WRITE
privilege,
and not the owner of the file,
times
is a NULL pointer, and write access is denied.
- EFAULT
times
is not a NULL pointer,
and it points outside the process's allocated address space.
The reliable detection of this error is implementation-dependent.
- EFAULT
path
points outside the process's allocated address space.
The reliable detection of this error is implementation-dependent.
- EINVAL
times
is not a NULL pointer, and access time or modification time
or both are negative.
- ENAMETOOLONG
The length of the specified path name exceeds
PATH_MAX
bytes, or the length of a component of the path name exceeds
NAME_MAX
bytes while
_POSIX_NO_TRUNC
is in effect.
- ENOENT
The named file does not exist.
- ENOTDIR
A component of the path prefix is not a directory.
- EPERM
The effective user ID is not a
user with the
OWNER
privilege,
and not the owner of the file, and
times
is not a NULL pointer.
- EROFS
The file system containing the file is mounted read-only.
DEPENDENCIES
NFS
utime()
may return
EPERM
when invoked on a remote file owned by
a superuser, or users with
DAC_WRITE
and
OWNER
privileges,
even if the invoking user has write permission on the file.
See
privileges(5)
for more information about privileged access on
systems that support fine-grained privileges.
STANDARDS CONFORMANCE
utime(): AES, SVID2, SVID3, XPG2, XPG3, XPG4, FIPS 151-2, POSIX.1
Printable version
