[apple/xnu.git] / bsd / man / man2 / utimes.2

.\"	$NetBSD: utimes.2,v 1.13 1999/03/22 19:45:11 garbled Exp $
.\"
.\" Copyright (c) 1990, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)utimes.2	8.1 (Berkeley) 6/4/93
.\" $FreeBSD: src/lib/libc/sys/utimes.2,v 1.8.2.4 2001/12/14 18:34:02 ru Exp $
.\"
.Dd June 4, 1993
.Dt UTIMES 2
.Os
.Sh NAME
.Nm futimes ,
.Nm utimes
.Nd set file access and modification times
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In sys/time.h
.Ft int
.Fo futimes
.Fa "int fildes"
.Fa "const struct timeval times[2]"
.Fc
.Ft int
.Fo utimes
.Fa "const char *path"
.Fa "const struct timeval times[2]"
.Fc
.Sh DESCRIPTION
The access and modification times of the file named by
.Fa path
or referenced by
.Fa fildes
are changed as specified by the argument
.Fa times .
.Pp
If
.Fa times
is
.Dv NULL ,
the access and modification times are set to the current time.
The caller must be the owner of the file, have permission to
write the file, or be the super-user.
.Pp
If
.Fa times
is
.Pf non- Dv NULL ,
it is assumed to point to an array of two timeval structures.
The access time is set to the value of the first element, and the
modification time is set to the value of the second element.
The caller must be the owner of the file or be the super-user.
.Pp
In either case, the inode-change-time of the file is set to the current
time.
.Sh RETURN VALUES
.Rv -std
.Sh ERRORS
The
.Fn utimes
system call 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
.Fa path
or
.Fa times
points outside the process's allocated address space.
.\" ===========
.It Bq Er EIO
An I/O error occurs while reading or writing the affected inode.
.\" ===========
.It Bq Er ELOOP
Too many symbolic links are encountered in translating the pathname.
This is taken to be indicative of a looping symbolic link.
.\" ===========
.It Bq Er ENAMETOOLONG
A component of a pathname exceeds
.Dv NAME_MAX
characters, or an entire path name exceeded
.Dv PATH_MAX
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
.Pp
The
.Fn futimes
system call will fail if:
.Bl -tag -width Er
.\" ===========
.It Bq Er EBADF
.Fa fildes
does not refer to a valid descriptor.
.El
.Pp
All of the functions will fail if:
.Bl -tag -width Er
.\" ===========
.It Bq Er EACCES
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
.Fa times
points outside the process's allocated address space.
.\" ===========
.It Bq Er EIO
An I/O error occurred while reading or writing the affected inode.
.\" ===========
.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 ,
.Xr utime 3
.Sh HISTORY
The
.Fn utimes
function call appeared in
.Bx 4.2 .
The
.Fn futimes
function call first appeared in
.Fx 3.0 .
Commit	Line	Data
9bccf70c A	1	.\" $NetBSD: utimes.2,v 1.13 1999/03/22 19:45:11 garbled Exp $
	2	.\"
	3	.\" Copyright (c) 1990, 1993
	4	.\" The Regents of the University of California. All rights reserved.
	5	.\"
	6	.\" Redistribution and use in source and binary forms, with or without
	7	.\" modification, are permitted provided that the following conditions
	8	.\" are met:
	9	.\" 1. Redistributions of source code must retain the above copyright
	10	.\" notice, this list of conditions and the following disclaimer.
	11	.\" 2. Redistributions in binary form must reproduce the above copyright
	12	.\" notice, this list of conditions and the following disclaimer in the
	13	.\" documentation and/or other materials provided with the distribution.
	14	.\" 3. All advertising materials mentioning features or use of this software
	15	.\" must display the following acknowledgement:
	16	.\" This product includes software developed by the University of
	17	.\" California, Berkeley and its contributors.
	18	.\" 4. Neither the name of the University nor the names of its contributors
	19	.\" may be used to endorse or promote products derived from this software
	20	.\" without specific prior written permission.
	21	.\"
	22	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	23	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	24	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	25	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	26	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	27	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	28	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	29	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	30	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	31	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	32	.\" SUCH DAMAGE.
	33	.\"
	34	.\" @(#)utimes.2 8.1 (Berkeley) 6/4/93
	35	.\" $FreeBSD: src/lib/libc/sys/utimes.2,v 1.8.2.4 2001/12/14 18:34:02 ru Exp $
	36	.\"
	37	.Dd June 4, 1993
	38	.Dt UTIMES 2
	39	.Os
	40	.Sh NAME
2d21ac55 A	41	.Nm futimes ,
2d21ac55 A	42	.Nm utimes
9bccf70c A	43	.Nd set file access and modification times
	44	.Sh LIBRARY
	45	.Lb libc
	46	.Sh SYNOPSIS
	47	.In sys/time.h
	48	.Ft int
2d21ac55 A	49	.Fo futimes
	50	.Fa "int fildes"
	51	.Fa "const struct timeval times[2]"
	52	.Fc
9bccf70c	53	.Ft int
2d21ac55 A	54	.Fo utimes
	55	.Fa "const char *path"
	56	.Fa "const struct timeval times[2]"
	57	.Fc
9bccf70c A	58	.Sh DESCRIPTION
	59	The access and modification times of the file named by
	60	.Fa path
	61	or referenced by
2d21ac55	62	.Fa fildes
9bccf70c A	63	are changed as specified by the argument
	64	.Fa times .
	65	.Pp
	66	If
	67	.Fa times
	68	is
	69	.Dv NULL ,
	70	the access and modification times are set to the current time.
	71	The caller must be the owner of the file, have permission to
	72	write the file, or be the super-user.
	73	.Pp
	74	If
	75	.Fa times
	76	is
	77	.Pf non- Dv NULL ,
	78	it is assumed to point to an array of two timeval structures.
	79	The access time is set to the value of the first element, and the
	80	modification time is set to the value of the second element.
	81	The caller must be the owner of the file or be the super-user.
	82	.Pp
	83	In either case, the inode-change-time of the file is set to the current
	84	time.
	85	.Sh RETURN VALUES
	86	.Rv -std
	87	.Sh ERRORS
2d21ac55	88	The
9bccf70c	89	.Fn utimes
2d21ac55	90	system call will fail if:
9bccf70c	91	.Bl -tag -width Er
2d21ac55	92	.\" ===========
9bccf70c A	93	.It Bq Er EACCES
	94	Search permission is denied for a component of the path prefix;
	95	or the
	96	.Fa times
	97	argument is
	98	.Dv NULL
	99	and the effective user ID of the process does not
	100	match the owner of the file, and is not the super-user, and write
	101	access is denied.
2d21ac55	102	.\" ===========
9bccf70c A	103	.It Bq Er EFAULT
	104	.Fa path
	105	or
	106	.Fa times
	107	points outside the process's allocated address space.
2d21ac55	108	.\" ===========
9bccf70c	109	.It Bq Er EIO
2d21ac55 A	110	An I/O error occurs while reading or writing the affected inode.
2d21ac55 A	111	.\" ===========
9bccf70c	112	.It Bq Er ELOOP
2d21ac55 A	113	Too many symbolic links are encountered in translating the pathname.
	114	This is taken to be indicative of a looping symbolic link.
	115	.\" ===========
9bccf70c	116	.It Bq Er ENAMETOOLONG
2d21ac55	117	A component of a pathname exceeds
9bccf70c A	118	.Dv NAME_MAX
	119	characters, or an entire path name exceeded
	120	.Dv PATH_MAX
	121	characters.
2d21ac55	122	.\" ===========
9bccf70c A	123	.It Bq Er ENOENT
9bccf70c A	124	The named file does not exist.
2d21ac55	125	.\" ===========
9bccf70c A	126	.It Bq Er ENOTDIR
9bccf70c A	127	A component of the path prefix is not a directory.
2d21ac55	128	.\" ===========
9bccf70c A	129	.It Bq Er EPERM
	130	The
	131	.Fa times
	132	argument is not
	133	.Dv NULL
	134	and the calling process's effective user ID
	135	does not match the owner of the file and is not the super-user.
2d21ac55	136	.\" ===========
9bccf70c A	137	.It Bq Er EROFS
	138	The file system containing the file is mounted read-only.
	139	.El
	140	.Pp
2d21ac55	141	The
9bccf70c	142	.Fn futimes
2d21ac55	143	system call will fail if:
9bccf70c	144	.Bl -tag -width Er
2d21ac55	145	.\" ===========
9bccf70c	146	.It Bq Er EBADF
2d21ac55	147	.Fa fildes
9bccf70c A	148	does not refer to a valid descriptor.
	149	.El
	150	.Pp
	151	All of the functions will fail if:
	152	.Bl -tag -width Er
2d21ac55	153	.\" ===========
9bccf70c A	154	.It Bq Er EACCES
	155	The
	156	.Fa times
	157	argument is
	158	.Dv NULL
	159	and the effective user ID of the process does not
	160	match the owner of the file, and is not the super-user, and write
	161	access is denied.
2d21ac55	162	.\" ===========
9bccf70c A	163	.It Bq Er EFAULT
	164	.Fa times
	165	points outside the process's allocated address space.
2d21ac55	166	.\" ===========
9bccf70c A	167	.It Bq Er EIO
9bccf70c A	168	An I/O error occurred while reading or writing the affected inode.
2d21ac55	169	.\" ===========
9bccf70c A	170	.It Bq Er EPERM
	171	The
	172	.Fa times
	173	argument is not
	174	.Dv NULL
	175	and the calling process's effective user ID
	176	does not match the owner of the file and is not the super-user.
2d21ac55	177	.\" ===========
9bccf70c A	178	.It Bq Er EROFS
	179	The file system containing the file is mounted read-only.
	180	.El
	181	.Sh SEE ALSO
	182	.Xr stat 2 ,
	183	.Xr utime 3
	184	.Sh HISTORY
	185	The
	186	.Fn utimes
	187	function call appeared in
	188	.Bx 4.2 .
	189	The
	190	.Fn futimes
	191	function call first appeared in
	192	.Fx 3.0 .