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