[unix-history] / usr / src / lib / libc / sys / utimes.2

.\" Copyright (c) 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" %sccs.include.redist.man%
.\"
.\"     @(#)utimes.2	8.1 (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
.Pf non- Dv NULL )
the caller must be the owner of the file or be the super-user.
.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 utimes
function call appeared in
.Bx 4.2 .
Commit	Line	Data
15715acc KB	1	.\" Copyright (c) 1990, 1993
15715acc KB	2	.\" The Regents of the University of California. All rights reserved.
14d9e8bc	3	.\"
931b8415	4	.\" %sccs.include.redist.man%
14d9e8bc	5	.\"
15715acc	6	.\" @(#)utimes.2 8.1 (Berkeley) %G%
931b8415 CL	7	.\"
	8	.Dd
	9	.Dt UTIMES 2
	10	.Os BSD 4
	11	.Sh NAME
	12	.Nm utimes
	13	.Nd set file access and modification times
	14	.Sh SYNOPSIS
	15	.Fd #include <sys/time.h>
	16	.Ft int
	17	.Fn utimes "const char file" "const struct timeval times"
	18	.Sh DESCRIPTION
14d9e8bc	19	The
931b8415 CL	20	.Fn utimes
	21	function sets the access and modification times of the named file from
	22	the structures in the argument array
	23	.Fa times .
	24	.Pp
	25	The first structure is the access time, and the second is the modification
	26	time.
	27	.Pp
	28	If the times are specified (the
	29	.Fa times
	30	argument is
9ba080b9 CL	31	.Pf non- Dv NULL )
9ba080b9 CL	32	the caller must be the owner of the file or be the super-user.
931b8415 CL	33	.Pp
	34	If the times are not specified (the
	35	.Fa times
	36	argument is
	37	.Dv NULL )
	38	the caller must be the owner of the file, have permission to
	39	write the file, or be the super-user.
	40	.Sh RETURN VALUES
481ecf6a	41	Upon successful completion, a value of 0 is returned.
931b8415 CL	42	Otherwise, a value of -1 is returned and
931b8415 CL	43	.Va errno
481ecf6a	44	is set to indicate the error.
931b8415 CL	45	.Sh ERRORS
	46	.Fn Utimes
	47	will fail if:
	48	.Bl -tag -width Er
	49	.It Bq Er EACCES
	50	Search permission is denied for a component of the path prefix;
	51	or the
	52	.Fa times
	53	argument is
	54	.Dv NULL
	55	and the effective user ID of the process does not
	56	match the owner of the file, and is not the super-user, and write
	57	access is denied.
	58	.It Bq Er EFAULT
	59	.Xr File
	60	or
	61	.Fa times
	62	points outside the process's allocated address space.
	63	.It Bq Er EINVAL
b5984ffe	64	The pathname contains a character with the high-order bit set.
931b8415 CL	65	.It Bq Er EIO
	66	An I/O error occurred while reading or writing the affected inode.
	67	.It Bq Er ELOOP
	68	Too many symbolic links were encountered in translating the pathname.
	69	.It Bq Er ENAMETOOLONG
b5984ffe KM	70	A component of a pathname exceeded 255 characters,
b5984ffe KM	71	or an entire path name exceeded 1023 characters.
931b8415	72	.It Bq Er ENOENT
481ecf6a	73	The named file does not exist.
931b8415 CL	74	.It Bq Er ENOTDIR
	75	A component of the path prefix is not a directory.
	76	.It Bq Er EPERM
	77	The
	78	.Fa times
	79	argument is not
	80	.Dv NULL
	81	and the calling process's effective user ID
	82	does not match the owner of the file and is not the super-user.
	83	.It Bq Er EROFS
481ecf6a	84	The file system containing the file is mounted read-only.
931b8415 CL	85	.El
	86	.Sh SEE ALSO
	87	.Xr stat 2
	88	.Sh HISTORY
	89	The
eb5956c3	90	.Nm utimes
931b8415 CL	91	function call appeared in
931b8415 CL	92	.Bx 4.2 .