| blob | 74a7dd02ee4843eb99cf46378e8c7b09e74b4f2a |
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 .\" 4. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
17 .\"
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
28 .\" SUCH DAMAGE.
29 .\"
30 .\" @(#)utimes.2 8.1 (Berkeley) 6/4/93
31 .\" $FreeBSD$
32 .\"
33 .Dd April 10, 2008
34 .Dt UTIMES 2
35 .Os
36 .Sh NAME
37 .Nm utimes ,
38 .Nm lutimes ,
39 .Nm futimes ,
40 .Nm futimesat
41 .Nd set file access and modification times
42 .Sh LIBRARY
43 .Lb libc
44 .Sh SYNOPSIS
45 .In sys/time.h
46 .Ft int
47 .Fn utimes "const char *path" "const struct timeval *times"
48 .Ft int
49 .Fn lutimes "const char *path" "const struct timeval *times"
50 .Ft int
51 .Fn futimes "int fd" "const struct timeval *times"
52 .Ft int
53 .Fn futimesat "int fd" "const char *path" "const struct timeval times[2]"
54 .Sh DESCRIPTION
55 The access and modification times of the file named by
56 .Fa path
57 or referenced by
58 .Fa fd
59 are changed as specified by the argument
60 .Fa times .
61 .Pp
62 If
63 .Fa times
64 is
65 .Dv NULL ,
66 the access and modification times are set to the current time.
67 The caller must be the owner of the file, have permission to
68 write the file, or be the super-user.
69 .Pp
70 If
71 .Fa times
72 is
73 .No non- Ns Dv NULL ,
74 it is assumed to point to an array of two timeval structures.
75 The access time is set to the value of the first element, and the
76 modification time is set to the value of the second element.
77 For file systems that support file birth (creation) times (such as
78 .Dv UFS2 ) ,
79 the birth time will be set to the value of the second element
80 if the second element is older than the currently set birth time.
81 To set both a birth time and a modification time,
82 two calls are required; the first to set the birth time
83 and the second to set the (presumably newer) modification time.
84 Ideally a new system call will be added that allows the setting
85 of all three times at once.
86 The caller must be the owner of the file or be the super-user.
87 .Pp
88 In either case, the inode-change-time of the file is set to the current
89 time.
90 .Pp
91 The
92 .Fn lutimes
93 system call
94 is like
95 .Fn utimes
96 except in the case where the named file is a symbolic link,
97 in which case
98 .Fn lutimes
99 changes the access and modification times of the link,
100 while
101 .Fn utimes
102 changes the times of the file the link references.
103 .Pp
104 The
105 .Fn futimesat
106 system call is equivalent to
107 .Fn utimes
108 except in the case where
109 .Fa path
110 specifies a relative path.
111 In this case the access and modification time
112 is set to that of a file relative to the directory associated with the file
113 descriptor
114 .Fa fd
115 instead of the current working directory.
116 If
117 .Fn futimesat
118 is passed the special value
119 .Dv AT_FDCWD
120 in the
121 .Fa fd
122 parameter, the current working directory is used and the behavior is identical to
123 a call to
124 .Fn utimes .
125 .Sh RETURN VALUES
126 .Rv -std
127 .Sh ERRORS
128 The
129 .Fn utimes
130 and
131 .Fn lutimes
132 system calls
133 will fail if:
134 .Bl -tag -width Er
135 .It Bq Er EACCES
136 Search permission is denied for a component of the path prefix;
137 or the
138 .Fa times
139 argument is
140 .Dv NULL
141 and the effective user ID of the process does not
142 match the owner of the file, and is not the super-user, and write
143 access is denied.
144 .It Bq Er EFAULT
145 The
146 .Fa path
147 or
148 .Fa times
149 argument
150 points outside the process's allocated address space.
151 .It Bq Er EIO
152 An I/O error occurred while reading or writing the affected inode.
153 .It Bq Er ELOOP
154 Too many symbolic links were encountered in translating the pathname.
155 .It Bq Er ENAMETOOLONG
156 A component of a pathname exceeded
157 .Dv NAME_MAX
158 characters, or an entire path name exceeded
159 .Dv PATH_MAX
160 characters.
161 .It Bq Er ENOENT
162 The named file does not exist.
163 .It Bq Er ENOTDIR
164 A component of the path prefix is not a directory.
165 .It Bq Er EPERM
166 The
167 .Fa times
168 argument is not
169 .Dv NULL
170 and the calling process's effective user ID
171 does not match the owner of the file and is not the super-user.
172 .It Bq Er EPERM
173 The named file has its immutable or append-only flag set, see the
174 .Xr chflags 2
175 manual page for more information.
176 .It Bq Er EROFS
177 The file system containing the file is mounted read-only.
178 .El
179 .Pp
180 The
181 .Fn futimes
182 system call
183 will fail if:
184 .Bl -tag -width Er
185 .It Bq Er EBADF
186 The
187 .Fa fd
188 argument
189 does not refer to a valid descriptor.
190 .El
191 .Pp
192 All of the system calls will fail if:
193 .Bl -tag -width Er
194 .It Bq Er EACCES
195 The
196 .Fa times
197 argument is
198 .Dv NULL
199 and the effective user ID of the process does not
200 match the owner of the file, and is not the super-user, and write
201 access is denied.
202 .It Bq Er EFAULT
203 The
204 .Fa times
205 argument
206 points outside the process's allocated address space.
207 .It Bq Er EINVAL
208 The
209 .Va tv_usec
210 component of at least one of the values specified by the
211 .Fa times
212 argument has a value less than 0 or greater than 999999.
213 .It Bq Er EIO
214 An I/O error occurred while reading or writing the affected inode.
215 .It Bq Er EPERM
216 The
217 .Fa times
218 argument is not
219 .Dv NULL
220 and the calling process's effective user ID
221 does not match the owner of the file and is not the super-user.
222 .It Bq Er EROFS
223 The file system containing the file is mounted read-only.
224 .El
225 .Pp
226 In addition to the errors returned by the
227 .Fn utimes ,
228 the
229 .Fn futimesat
230 may fail if:
231 .Bl -tag -width Er
232 .It Bq Er EBADF
233 The
234 .Fa path
235 argument does not specify an absolute path and the
236 .Fa fd
237 argument is neither
238 .Dv AT_FDCWD
239 nor a valid file descriptor open for searching.
240 .It Bq Er ENOTDIR
241 The
242 .Fa path
243 argument is not an absolute path and
244 .Fa fd
245 is neither
246 .Dv AT_FDCWD
247 nor a file descriptor associated with a directory.
248 .El
249 .Sh SEE ALSO
250 .Xr chflags 2 ,
251 .Xr stat 2 ,
252 .Xr utime 3
253 .Sh STANDARDS
254 The
255 .Fn utimes
256 function is expected to conform to
257 .St -xpg4.2 .
258 The
259 .Fn futimesat
260 system call follows The Open Group Extended API Set 2 specification.
261 .Sh HISTORY
262 The
263 .Fn utimes
264 system call appeared in
265 .Bx 4.2 .
266 The
267 .Fn futimes
268 and
269 .Fn lutimes
270 system calls first appeared in
271 .Fx 3.0 .
272 The
273 .Fn futimesat
274 system call appeared in
275 .Fx 8.0 .