usr/src/lib/libc/sys/utimes.2

.\" Copyright (c) 1990 The Regents of the University of California.
.\" All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)utimes.2    6.6 (Berkeley) %G%
.\"
.Dd
.Dt UTIMES 2
.Os BSD 4
.Sh NAME
.Nm utimes
.Nd set file access and modification times
.Sh SYNOPSIS
.Fd #include <sys/time.h>
.Ft int
.Fn utimes "const char *file" "const struct timeval *times"
.Sh DESCRIPTION
The
.Fn utimes
function sets the access and modification times of the named file from
the structures in the argument array
.Fa times .
.Pp
The first structure is the access time, and the second is the modification
time.
.Pp
If the times are specified (the
.Fa times
argument is
.No non- Ns Dv NULL )
the caller must be the owner of the file or be the superuser.
.Pp
If the times are not specified (the
.Fa times
argument is
.Dv NULL )
the caller must be the owner of the file, have permission to
write the file, or be the super-user.
.Sh RETURN VALUES
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn Utimes
will fail if:
.Bl -tag -width Er
.It Bq Er EACCES
Search permission is denied for a component of the path prefix;
or the
.Fa times
argument is
.Dv NULL
and the effective user ID of the process does not
match the owner of the file, and is not the super-user, and write
access is denied.
.It Bq Er EFAULT
.Xr File
or
.Fa times
points outside the process's allocated address space.
.It Bq Er EINVAL
The pathname contains a character with the high-order bit set.
.It Bq Er EIO
An I/O error occurred while reading or writing the affected inode.
.It Bq Er ELOOP
Too many symbolic links were encountered in translating the pathname.
.It Bq Er ENAMETOOLONG
A component of a pathname exceeded 255 characters,
or an entire path name exceeded 1023 characters.
.It Bq Er ENOENT
The named file does not exist.
.It Bq Er ENOTDIR
A component of the path prefix is not a directory.
.It Bq Er EPERM
The
.Fa times
argument is not
.Dv NULL
and the calling process's effective user ID
does not match the owner of the file and is not the super-user.
.It Bq Er EROFS
The file system containing the file is mounted read-only.
.El
.Sh SEE ALSO
.Xr stat 2
.Sh HISTORY
The
.Nm
function call appeared in
.Bx 4.2 .