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.man.txt
+++ new/usr/src/man/man2/utimes.2.man.txt
1 1 UTIMES(2) System Calls UTIMES(2)
2 2
3 3
4 4
5 5 NAME
6 - utimes, futimesat - set file access and modification times
6 + utimes, lutimes, futimes, futimesat, utimens, utimensat - set file
7 + access and modification times
7 8
8 9 SYNOPSIS
9 10 #include <sys/time.h>
10 11
11 12 int utimes(const char *path, const struct timeval times[2]);
12 13
13 14
15 + int lutimes(const char *path, const struct timeval times[2]);
16 +
17 +
18 + int futimes(int fildes, const struct timeval times[2]);
19 +
20 +
14 21 int futimesat(int fildes, const char *path,
15 22 const struct timeval times[2]);
16 23
17 24
18 25 #include <sys/stat.h>
19 26
20 - int futimens(int filedes, const timespec_t nstimes[2]);
27 + int futimens(int fildes, const timespec_t nstimes[2]);
21 28
22 - int utimensat(int filedes, const char *path,
29 + int utimensat(int fildes, const char *path,
23 30 const timespec_t nstimes[2], int flag);
24 31
25 32
26 33 DESCRIPTION
27 34 The utimes() function sets the access and modification times of the
28 35 file pointed to by the path argument to the value of the times
29 36 argument. It allows time specifications accurate to the microsecond.
30 37
31 38
39 + The lutimes() function operates like utimes() except if path points to
40 + a symbolic link; in that case lutimes() changes the access and
41 + modifications times of the link, while utimes() changes the file that
42 + is referenced by the link.
43 +
44 +
45 + The futimes() function sets the access and modification times of the
46 + file referenced by the file descriptor fildes.
47 +
48 +
32 49 The futimesat() function also sets access and modification times. See
33 50 fsattr(5). If path is a relative path name, however, futimesat()
34 51 resolves the path relative to the fildes argument rather than the
35 52 current working directory. If fildes is set to AT_FDCWD, defined in
36 53 <fcntl.h>, futimesat() resolves the path relative to the current
37 54 working directory. If path is a null pointer, futimesat() sets the
38 55 access and modification times on the file referenced by fildes. The
39 - fildes argument is ignored even when futimesat() is provided with an
40 - absolute path.
56 + fildes argument is ignored if futimesat() is provided with an absolute
57 + path.
41 58
42 59
43 60 The times argument is an array of timeval structures. The first array
44 61 member represents the date and time of last access, and the second
45 62 member represents the date and time of last modification. The times in
46 63 the timeval structure are measured in seconds and microseconds since
47 64 the Epoch, although rounding toward the nearest second may occur.
48 65
49 66
50 67 If the times argument is a null pointer, the access and modification
51 68 times of the file are set to the current time. The effective user ID
|
↓ open down ↓ |
1 lines elided |
↑ open up ↑ |
52 69 of the process must be the same as the owner of the file, or must have
53 70 write access to the file or the {PRIV_FILE_OWNER} privilege to use this
54 71 call in this manner. Upon completion, utimes() will mark the time of
55 72 the last file status change, st_ctime, for update.
56 73
57 74
58 75 The futimens() and utimensat() functions also set access and
59 76 modification times; however, instead of taking struct timeval, they
60 77 take timespec_t which allows for nanosecond granularity. The futimens()
61 78 function sets the access and modification times on the file descriptor
62 - referenced by filedes.
79 + referenced by fildes.
63 80
64 81
65 82 The utimensat() function determines the file to set the access and
66 - modification times in an similar way to futemsat(). If the argument
67 - path is an absolute path, then the argument filedes is ignored;
83 + modification times in an similar way to futimesat(). If the argument
84 + path is an absolute path, then the argument fildes is ignored;
68 85 otherwise, path is interpreted as a path relative to the directory
69 - specified by filedes. If filedes is set to AT_FDCWD, then path is
86 + specified by fildes. If fildes is set to AT_FDCWD, then path is
70 87 resolved relative to the current working directory. The behavior when
71 88 encountering symbolic links may be controlled by the value of the flag
72 89 argument. If the value of flag is the constant AT_SYMLINK_NOFOLLOW,
73 90 then when a symbolic link is encountered while resolving a path, it
74 - will not be followed. Otherwise, the value of flag should be 0.
91 + will not be followed. Otherwise, the value of flag should be 0. Note
92 + that, unlike futimesat(), utimensat() does not accept a null pointer
93 + for the path argument.
75 94
76 95 RETURN VALUES
77 96 Upon successful completion, 0 is returned. Otherwise, -1 is returned,
78 97 errno is set to indicate the error, and the file times will not be
79 98 affected.
80 99
81 100 ERRORS
82 - The utimes(), futimesat(), futimens(), and utimensat() functions will
83 - fail if:
101 + The utimes(), lutimes(), futimes(), futimesat(), futimens(), and
102 + utimensat() functions will fail if:
84 103
85 104 EACCES
86 105 Search permission is denied by a component of the path
87 106 prefix; or the times argument is a null pointer and the
88 107 effective user ID of the process does not match the
89 108 owner of the file and write access is denied.
90 109
91 110
92 111 EFAULT
93 112 The path or times argument points to an illegal
94 - address. For futimesat(), path might have the value
95 - NULL if the fildes argument refers to a valid open file
96 - descriptor.
113 + address.
97 114
98 115
99 116 EINTR
100 117 A signal was caught during the execution of the
101 - utimes(), futimesat(), futimens(), or utimensat()
102 - functions.
118 + utimes(), lutimes(), futimes(), futimesat(),
119 + futimens(), or utimensat() functions.
103 120
104 121
105 122 EINVAL
106 123 The number of microseconds specified in one or both of
107 124 the timeval structures pointed to by times was greater
108 125 than or equal to 1,000,000 or less than 0. The number
109 126 of nanoseconds specified in one or both of the
110 127 timespec_t structures pointed to by nstimes was greater
111 128 than or equal to 1,000,000,000 or less than 0.
112 129
113 130
114 131 EIO
115 132 An I/O error occurred while reading from or writing to
116 133 the file system.
117 134
118 135
119 136 ELOOP
120 137 Too many symbolic links were encountered in resolving
121 138 path.
122 139
123 140
124 141 ENAMETOOLONG
125 142 The length of the path argument exceeds {PATH_MAX} or a
126 143 pathname component is longer than {NAME_MAX}.
127 144
128 145
129 146 ENOLINK
130 147 The path argument points to a remote machine and the
131 148 link to that machine is no longer active.
132 149
133 150
134 151 ENOENT
135 152 A component of path does not name an existing file or
136 153 path is an empty string.
137 154
138 155
139 156 ENOTDIR
140 157 A component of the path prefix is not a directory or
141 158 the path argument is relative and the fildes argument
142 159 is not AT_FDCWD or does not refer to a valid directory.
143 160
144 161
145 162 EPERM
146 163 The times argument is not a null pointer and the
147 164 calling process's effective user ID has write access to
148 165 the file but does not match the owner of the file and
149 166 the calling process does not have the appropriate
150 167 privileges.
151 168
152 169
153 170 EROFS
154 171 The file system containing the file is read-only.
155 172
156 173
157 174
158 175 The utimes(), futimesat(), and utimensat() functions may fail if:
159 176
160 177 ENAMETOOLONG
161 178 Path name resolution of a symbolic link produced an
162 179 intermediate result whose length exceeds {PATH_MAX}.
163 180
164 181
165 182 ATTRIBUTES
166 183 See attributes(5) for descriptions of the following attributes:
167 184
168 185
169 186
170 187
171 188 +--------------------+-----------------+
172 189 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|
↓ open down ↓ |
60 lines elided |
↑ open up ↑ |
173 190 +--------------------+-----------------+
174 191 |Interface Stability | Committed |
175 192 +--------------------+-----------------+
176 193 |Standard | See below. |
177 194 +--------------------+-----------------+
178 195
179 196
180 197 For utimes(), utimensat() and futimensat(), see standards(5).
181 198
182 199 SEE ALSO
183 - futimens(2), stat(2), utime(2), attributes(5), fsattr(5), standards(5)
200 + fBstat(2), utime(2), attributes(5), fsattr(5), standards(5)
184 201
185 202
186 203
187 - December 20, 2014 UTIMES(2)
204 + September 6, 2020 UTIMES(2)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX