xnu-1228.7.58.tar.gz
[apple/xnu.git] / bsd / man / man2 / utimes.2
0 / 192 (  0%)
CommitLineData
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
41.Nm futimes ,
42.Nm utimes
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
49.Fo futimes
50.Fa "int fildes"
51.Fa "const struct timeval times[2]"
52.Fc
53.Ft int
54.Fo utimes
55.Fa "const char *path"
56.Fa "const struct timeval times[2]"
57.Fc
58.Sh DESCRIPTION
59The access and modification times of the file named by
60.Fa path
61or referenced by
62.Fa fildes
63are changed as specified by the argument
64.Fa times .
65.Pp
66If
67.Fa times
68is
69.Dv NULL ,
70the access and modification times are set to the current time.
71The caller must be the owner of the file, have permission to
72write the file, or be the super-user.
73.Pp
74If
75.Fa times
76is
77.Pf non- Dv NULL ,
78it is assumed to point to an array of two timeval structures.
79The access time is set to the value of the first element, and the
80modification time is set to the value of the second element.
81The caller must be the owner of the file or be the super-user.
82.Pp
83In either case, the inode-change-time of the file is set to the current
84time.
85.Sh RETURN VALUES
86.Rv -std
87.Sh ERRORS
88The
89.Fn utimes
90system call will fail if:
91.Bl -tag -width Er
92.\" ===========
93.It Bq Er EACCES
94Search permission is denied for a component of the path prefix;
95or the
96.Fa times
97argument is
98.Dv NULL
99and the effective user ID of the process does not
100match the owner of the file, and is not the super-user, and write
101access is denied.
102.\" ===========
103.It Bq Er EFAULT
104.Fa path
105or
106.Fa times
107points outside the process's allocated address space.
108.\" ===========
109.It Bq Er EIO
110An I/O error occurs while reading or writing the affected inode.
111.\" ===========
112.It Bq Er ELOOP
113Too many symbolic links are encountered in translating the pathname.
114This is taken to be indicative of a looping symbolic link.
115.\" ===========
116.It Bq Er ENAMETOOLONG
117A component of a pathname exceeds
118.Dv NAME_MAX
119characters, or an entire path name exceeded
120.Dv PATH_MAX
121characters.
122.\" ===========
123.It Bq Er ENOENT
124The named file does not exist.
125.\" ===========
126.It Bq Er ENOTDIR
127A component of the path prefix is not a directory.
128.\" ===========
129.It Bq Er EPERM
130The
131.Fa times
132argument is not
133.Dv NULL
134and the calling process's effective user ID
135does not match the owner of the file and is not the super-user.
136.\" ===========
137.It Bq Er EROFS
138The file system containing the file is mounted read-only.
139.El
140.Pp
141The
142.Fn futimes
143system call will fail if:
144.Bl -tag -width Er
145.\" ===========
146.It Bq Er EBADF
147.Fa fildes
148does not refer to a valid descriptor.
149.El
150.Pp
151All of the functions will fail if:
152.Bl -tag -width Er
153.\" ===========
154.It Bq Er EACCES
155The
156.Fa times
157argument is
158.Dv NULL
159and the effective user ID of the process does not
160match the owner of the file, and is not the super-user, and write
161access is denied.
162.\" ===========
163.It Bq Er EFAULT
164.Fa times
165points outside the process's allocated address space.
166.\" ===========
167.It Bq Er EIO
168An I/O error occurred while reading or writing the affected inode.
169.\" ===========
170.It Bq Er EPERM
171The
172.Fa times
173argument is not
174.Dv NULL
175and the calling process's effective user ID
176does not match the owner of the file and is not the super-user.
177.\" ===========
178.It Bq Er EROFS
179The 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
185The
186.Fn utimes
187function call appeared in
188.Bx 4.2 .
189The
190.Fn futimes
191function call first appeared in
192.Fx 3.0 .