Print this page
13111 Want futimes() and lutimes() functions
Change-ID: I3be82d4242255a4100f8c35db373eb9140402fc4
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man2/utimes.2
+++ new/usr/src/man/man2/utimes.2
1 1 .\"
2 2 .\" Sun Microsystems, Inc. gratefully acknowledges The Open Group for
3 3 .\" permission to reproduce portions of its copyrighted documentation.
4 4 .\" Original documentation from The Open Group can be obtained online at
5 5 .\" http://www.opengroup.org/bookstore/.
6 6 .\"
7 7 .\" The Institute of Electrical and Electronics Engineers and The Open
8 8 .\" Group, have given us permission to reprint portions of their
9 9 .\" documentation.
10 10 .\"
11 11 .\" In the following statement, the phrase ``this text'' refers to portions
12 12 .\" of the system documentation.
13 13 .\"
14 14 .\" Portions of this text are reprinted and reproduced in electronic form
15 15 .\" in the SunOS Reference Manual, from IEEE Std 1003.1, 2004 Edition,
16 16 .\" Standard for Information Technology -- Portable Operating System
17 17 .\" Interface (POSIX), The Open Group Base Specifications Issue 6,
18 18 .\" Copyright (C) 2001-2004 by the Institute of Electrical and Electronics
19 19 .\" Engineers, Inc and The Open Group. In the event of any discrepancy
20 20 .\" between these versions and the original IEEE and The Open Group
21 21 .\" Standard, the original IEEE and The Open Group Standard is the referee
22 22 .\" document. The original Standard can be obtained online at
23 23 .\" http://www.opengroup.org/unix/online.html.
24 24 .\"
25 25 .\" This notice shall appear on any product containing this material.
26 26 .\"
27 27 .\" The contents of this file are subject to the terms of the
28 28 .\" Common Development and Distribution License (the "License").
29 29 .\" You may not use this file except in compliance with the License.
30 30 .\"
31 31 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
32 32 .\" or http://www.opensolaris.org/os/licensing.
33 33 .\" See the License for the specific language governing permissions
34 34 .\" and limitations under the License.
35 35 .\"
|
↓ open down ↓ |
35 lines elided |
↑ open up ↑ |
36 36 .\" When distributing Covered Code, include this CDDL HEADER in each
37 37 .\" file and include the License file at usr/src/OPENSOLARIS.LICENSE.
38 38 .\" If applicable, add the following below this CDDL HEADER, with the
39 39 .\" fields enclosed by brackets "[]" replaced with your own identifying
40 40 .\" information: Portions Copyright [yyyy] [name of copyright owner]
41 41 .\"
42 42 .\"
43 43 .\" Portions Copyright (c) 1992, X/Open Company Limited. All Rights Reserved.
44 44 .\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved.
45 45 .\" Copyright (c) 2014, Joyent, Inc.
46 +.\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
46 47 .\"
47 -.TH UTIMES 2 "Dec 20, 2014"
48 +.TH UTIMES 2 "Sep 06, 2020"
48 49 .SH NAME
49 -utimes, futimesat \- set file access and modification times
50 +utimes, lutimes, futimes, futimesat, utimens, utimensat \- set file access and modification times
50 51 .SH SYNOPSIS
51 -.LP
52 52 .nf
53 53 #include <sys/time.h>
54 54
55 55 \fBint\fR \fButimes\fR(\fBconst char *\fR\fIpath\fR, \fBconst struct timeval\fR \fItimes\fR[2]);
56 56 .fi
57 57
58 58 .LP
59 59 .nf
60 +\fBint\fR \fBlutimes\fR(\fBconst char *\fR\fIpath\fR, \fBconst struct timeval\fR \fItimes\fR[2]);
61 +.fi
62 +
63 +.LP
64 +.nf
65 +\fBint\fR \fBfutimes\fR(\fBint\fR \fIfildes\fR, \fBconst struct timeval\fR \fItimes\fR[2]);
66 +.fi
67 +
68 +.LP
69 +.nf
60 70 \fBint\fR \fBfutimesat\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIpath\fR,
61 71 \fBconst struct timeval\fR \fItimes\fR[2]);
62 72 .fi
63 73
64 74 .LP
65 75 .nf
66 76 #include <sys/stat.h>
67 77
68 -\fBint\fR \fBfutimens\fR(\fBint\fR \fIfiledes\fR, \fBconst timespec_t\fR \fInstimes[2]\fR);
78 +\fBint\fR \fBfutimens\fR(\fBint\fR \fIfildes\fR, \fBconst timespec_t\fR \fInstimes[2]\fR);
69 79
70 -\fBint\fR \fButimensat\fR(\fBint\fR \fIfiledes\fR, \fBconst char *\fR\fIpath\fR,
80 +\fBint\fR \fButimensat\fR(\fBint\fR \fIfildes\fR, \fBconst char *\fR\fIpath\fR,
71 81 \fBconst timespec_t\fR \fInstimes[2]\fR, \fBint\fR \fIflag\fR);
72 82
73 83 .SH DESCRIPTION
74 -.LP
75 84 The \fButimes()\fR function sets the access and modification times of the file
76 85 pointed to by the \fIpath\fR argument to the value of the \fItimes\fR argument.
77 86 It allows time specifications accurate to the microsecond.
78 87 .sp
79 88 .LP
89 +The \fBlutimes()\fR function operates like \fButimes()\fR except if \fIpath\fR
90 +points to a symbolic link; in that case \fBlutimes()\fR changes the access and
91 +modifications times of the link, while \fButimes()\fR changes the file that
92 +is referenced by the link.
93 +.sp
94 +.LP
95 +The \fBfutimes()\fR function sets the access and modification times of the
96 +file referenced by the file descriptor \fIfildes\fR.
97 +.sp
98 +.LP
80 99 The \fBfutimesat()\fR function also sets access and modification times. See
81 100 \fBfsattr\fR(5). If \fIpath\fR is a relative path name, however,
82 101 \fBfutimesat()\fR resolves the path relative to the \fIfildes\fR argument
83 102 rather than the current working directory. If \fIfildes\fR is set to
84 103 \fBAT_FDCWD\fR, defined in <\fBfcntl.h\fR>, \fBfutimesat()\fR resolves the path
85 104 relative to the current working directory. If \fIpath\fR is a null pointer,
86 105 \fBfutimesat()\fR sets the access and modification times on the file referenced
87 -by \fIfildes\fR. The \fIfildes\fR argument is ignored even when
106 +by \fIfildes\fR. The \fIfildes\fR argument is ignored if
88 107 \fBfutimesat()\fR is provided with an absolute path.
89 108 .sp
90 109 .LP
91 110 The \fItimes\fR argument is an array of \fBtimeval\fR structures. The first
92 111 array member represents the date and time of last access, and the second member
93 112 represents the date and time of last modification. The times in the
94 113 \fBtimeval\fR structure are measured in seconds and microseconds since the
95 114 Epoch, although rounding toward the nearest second may occur.
96 115 .sp
97 116 .LP
98 117 If the \fItimes\fR argument is a null pointer, the access and modification
99 118 times of the file are set to the current time. The effective user \fBID\fR of
|
↓ open down ↓ |
2 lines elided |
↑ open up ↑ |
100 119 the process must be the same as the owner of the file, or must have write
101 120 access to the file or the {\fBPRIV_FILE_OWNER\fR} privilege to use this call in
102 121 this manner. Upon completion, \fButimes()\fR will mark the time of the last
103 122 file status change, \fBst_ctime\fR, for update.
104 123 .sp
105 124 .LP
106 125 The \fBfutimens()\fR and \fButimensat()\fR functions also set access and
107 126 modification times; however, instead of taking \fBstruct timeval\fR, they take
108 127 \fBtimespec_t\fR which allows for nanosecond granularity. The \fBfutimens()\fR
109 128 function sets the access and modification times on the file descriptor
110 -referenced by \fIfiledes\fR.
129 +referenced by \fIfildes\fR.
111 130 .sp
112 131 .LP
113 132 The \fButimensat()\fR function determines the file to set the access and
114 -modification times in an similar way to \fBfutemsat()\fR. If the argument
115 -\fIpath\fR is an absolute path, then the argument \fIfiledes\fR is ignored;
133 +modification times in an similar way to \fBfutimesat()\fR. If the argument
134 +\fIpath\fR is an absolute path, then the argument \fIfildes\fR is ignored;
116 135 otherwise, \fIpath\fR is interpreted as a path relative to the directory
117 -specified by \fIfiledes\fR. If \fIfiledes\fR is set to \fBAT_FDCWD\fR, then
136 +specified by \fIfildes\fR. If \fIfildes\fR is set to \fBAT_FDCWD\fR, then
118 137 \fIpath\fR is resolved relative to the current working directory. The behavior
119 138 when encountering symbolic links may be controlled by the value of the
120 139 \fIflag\fR argument. If the value of flag is the constant
121 140 \fBAT_SYMLINK_NOFOLLOW\fR, then when a symbolic link is encountered while
122 141 resolving a path, it will not be followed. Otherwise, the value of \fIflag\fR
123 -should be \fB0\fR.
142 +should be \fB0\fR. Note that, unlike \fBfutimesat()\fR, \fButimensat()\fR
143 +does not accept a null pointer for the \fIpath\fR argument.
124 144 .SH RETURN VALUES
125 -.LP
126 145 Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
127 146 returned, \fBerrno\fR is set to indicate the error, and the file times will not
128 147 be affected.
129 148 .SH ERRORS
130 -.LP
131 -The \fButimes()\fR, \fBfutimesat()\fR, \fBfutimens()\fR, and \fButimensat()\fR
149 +The \fButimes()\fR, \fBlutimes()\fR, \fBfutimes()\fR, \fBfutimesat()\fR,
150 +\fBfutimens()\fR, and \fButimensat()\fR
132 151 functions will fail if:
133 152 .sp
134 153 .ne 2
135 154 .na
136 155 \fB\fBEACCES\fR\fR
137 156 .ad
138 157 .RS 16n
139 158 Search permission is denied by a component of the path prefix; or the
140 159 \fItimes\fR argument is a null pointer and the effective user \fBID\fR of the
141 160 process does not match the owner of the file and write access is denied.
142 161 .RE
143 162
144 163 .sp
145 164 .ne 2
146 165 .na
147 166 \fB\fBEFAULT\fR\fR
148 167 .ad
149 168 .RS 16n
150 -The \fIpath\fR or \fItimes\fR argument points to an illegal address. For
151 -\fBfutimesat()\fR, \fIpath\fR might have the value \fINULL\fR if the
152 -\fIfildes\fR argument refers to a valid open file descriptor.
169 +The \fIpath\fR or \fItimes\fR argument points to an illegal address.
153 170 .RE
154 171
155 172 .sp
156 173 .ne 2
157 174 .na
158 175 \fB\fBEINTR\fR\fR
159 176 .ad
160 177 .RS 16n
161 178 A signal was caught during the execution of the \fButimes()\fR,
179 +\fBlutimes()\fR, \fBfutimes()\fR,
162 180 \fBfutimesat()\fR, \fBfutimens()\fR, or \fButimensat()\fR functions.
163 181 .RE
164 182
165 183 .sp
166 184 .ne 2
167 185 .na
168 186 \fB\fBEINVAL\fR\fR
169 187 .ad
170 188 .RS 16n
171 189 The number of microseconds specified in one or both of the \fBtimeval\fR
172 190 structures pointed to by \fItimes\fR was greater than or equal to 1,000,000 or
173 191 less than 0. The number of nanoseconds specified in one or both of the
174 192 \fBtimespec_t\fR structures pointed to by \fInstimes\fR was greater than or
175 193 equal to 1,000,000,000 or less than 0.
176 194 .RE
177 195
178 196 .sp
179 197 .ne 2
180 198 .na
181 199 \fB\fBEIO\fR\fR
182 200 .ad
183 201 .RS 16n
184 202 An I/O error occurred while reading from or writing to the file system.
185 203 .RE
186 204
187 205 .sp
188 206 .ne 2
189 207 .na
190 208 \fB\fBELOOP\fR\fR
191 209 .ad
192 210 .RS 16n
193 211 Too many symbolic links were encountered in resolving \fIpath\fR.
194 212 .RE
195 213
196 214 .sp
197 215 .ne 2
198 216 .na
199 217 \fB\fBENAMETOOLONG\fR\fR
200 218 .ad
201 219 .RS 16n
202 220 The length of the \fIpath\fR argument exceeds {\fIPATH_MAX\fR} or a pathname
203 221 component is longer than {\fINAME_MAX\fR}.
204 222 .RE
205 223
206 224 .sp
207 225 .ne 2
208 226 .na
209 227 \fB\fBENOLINK\fR\fR
210 228 .ad
211 229 .RS 16n
212 230 The \fIpath\fR argument points to a remote machine and the link to that machine
213 231 is no longer active.
214 232 .RE
215 233
216 234 .sp
217 235 .ne 2
218 236 .na
219 237 \fB\fBENOENT\fR\fR
220 238 .ad
221 239 .RS 16n
222 240 A component of \fIpath\fR does not name an existing file or \fIpath\fR is an
223 241 empty string.
224 242 .RE
225 243
226 244 .sp
227 245 .ne 2
228 246 .na
229 247 \fB\fBENOTDIR\fR\fR
230 248 .ad
231 249 .RS 16n
232 250 A component of the path prefix is not a directory or the \fIpath\fR argument is
233 251 relative and the \fIfildes\fR argument is not \fBAT_FDCWD\fR or does not refer
234 252 to a valid directory.
235 253 .RE
236 254
237 255 .sp
238 256 .ne 2
239 257 .na
240 258 \fB\fBEPERM\fR\fR
241 259 .ad
242 260 .RS 16n
243 261 The \fItimes\fR argument is not a null pointer and the calling process's
244 262 effective user \fBID\fR has write access to the file but does not match the
245 263 owner of the file and the calling process does not have the appropriate
246 264 privileges.
247 265 .RE
248 266
249 267 .sp
250 268 .ne 2
251 269 .na
252 270 \fB\fBEROFS\fR\fR
253 271 .ad
254 272 .RS 16n
255 273 The file system containing the file is read-only.
256 274 .RE
257 275
258 276 .sp
259 277 .LP
260 278 The \fButimes()\fR, \fBfutimesat()\fR, and \fButimensat()\fR functions may fail
261 279 if:
262 280 .sp
|
↓ open down ↓ |
91 lines elided |
↑ open up ↑ |
263 281 .ne 2
264 282 .na
265 283 \fB\fBENAMETOOLONG\fR\fR
266 284 .ad
267 285 .RS 16n
268 286 Path name resolution of a symbolic link produced an intermediate result whose
269 287 length exceeds {\fIPATH_MAX\fR}.
270 288 .RE
271 289
272 290 .SH ATTRIBUTES
273 -.LP
274 291 See \fBattributes\fR(5) for descriptions of the following attributes:
275 292 .sp
276 293
277 294 .sp
278 295 .TS
279 296 box;
280 297 c | c
281 298 l | l .
282 299 ATTRIBUTE TYPE ATTRIBUTE VALUE
283 300 _
284 301 Interface Stability Committed
285 302 _
286 303 Standard See below.
287 304 .TE
288 305
289 306 .sp
290 307 .LP
291 308 For \fButimes()\fR, \fButimensat()\fR and \fBfutimensat()\fR, see \fBstandards\fR(5).
292 309 .SH SEE ALSO
293 -.LP
294 -\fBfutimens\fR(2), \fBstat\fR(2), \fButime\fR(2), \fBattributes\fR(5),
310 +fBstat\fR(2), \fButime\fR(2), \fBattributes\fR(5),
295 311 \fBfsattr\fR(5), \fBstandards\fR(5)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX