1 UTIMES(2) System Calls UTIMES(2)
2
3
4
5 NAME
6 utimes, futimesat - set file access and modification times
7
8 SYNOPSIS
9 #include <sys/time.h>
10
11 int utimes(const char *path, const struct timeval times[2]);
12
13
14 int futimesat(int fildes, const char *path,
15 const struct timeval times[2]);
16
17
18 #include <sys/stat.h>
19
20 int futimens(int filedes, const timespec_t nstimes[2]);
21
22 int utimensat(int filedes, const char *path,
23 const timespec_t nstimes[2], int flag);
24
25
26 DESCRIPTION
27 The utimes() function sets the access and modification times of the
28 file pointed to by the path argument to the value of the times
29 argument. It allows time specifications accurate to the microsecond.
30
31
32 The futimesat() function also sets access and modification times. See
33 fsattr(5). If path is a relative path name, however, futimesat()
34 resolves the path relative to the fildes argument rather than the
35 current working directory. If fildes is set to AT_FDCWD, defined in
36 <fcntl.h>, futimesat() resolves the path relative to the current
37 working directory. If path is a null pointer, futimesat() sets the
38 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.
41
42
43 The times argument is an array of timeval structures. The first array
44 member represents the date and time of last access, and the second
45 member represents the date and time of last modification. The times in
46 the timeval structure are measured in seconds and microseconds since
47 the Epoch, although rounding toward the nearest second may occur.
48
49
50 If the times argument is a null pointer, the access and modification
51 times of the file are set to the current time. The effective user ID
52 of the process must be the same as the owner of the file, or must have
53 write access to the file or the {PRIV_FILE_OWNER} privilege to use this
54 call in this manner. Upon completion, utimes() will mark the time of
55 the last file status change, st_ctime, for update.
56
57
58 The futimens() and utimensat() functions also set access and
59 modification times; however, instead of taking struct timeval, they
60 take timespec_t which allows for nanosecond granularity. The futimens()
61 function sets the access and modification times on the file descriptor
62 referenced by filedes.
63
64
65 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;
68 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
70 resolved relative to the current working directory. The behavior when
71 encountering symbolic links may be controlled by the value of the flag
72 argument. If the value of flag is the constant AT_SYMLINK_NOFOLLOW,
73 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.
75
76 RETURN VALUES
77 Upon successful completion, 0 is returned. Otherwise, -1 is returned,
78 errno is set to indicate the error, and the file times will not be
79 affected.
80
81 ERRORS
82 The utimes(), futimesat(), futimens(), and utimensat() functions will
83 fail if:
84
85 EACCES
86 Search permission is denied by a component of the path
87 prefix; or the times argument is a null pointer and the
88 effective user ID of the process does not match the
89 owner of the file and write access is denied.
90
91
92 EFAULT
93 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.
97
98
99 EINTR
100 A signal was caught during the execution of the
101 utimes(), futimesat(), futimens(), or utimensat()
102 functions.
103
104
105 EINVAL
106 The number of microseconds specified in one or both of
107 the timeval structures pointed to by times was greater
108 than or equal to 1,000,000 or less than 0. The number
109 of nanoseconds specified in one or both of the
110 timespec_t structures pointed to by nstimes was greater
111 than or equal to 1,000,000,000 or less than 0.
112
113
114 EIO
115 An I/O error occurred while reading from or writing to
116 the file system.
117
118
119 ELOOP
120 Too many symbolic links were encountered in resolving
121 path.
122
163
164
165 ATTRIBUTES
166 See attributes(5) for descriptions of the following attributes:
167
168
169
170
171 +--------------------+-----------------+
172 | ATTRIBUTE TYPE | ATTRIBUTE VALUE |
173 +--------------------+-----------------+
174 |Interface Stability | Committed |
175 +--------------------+-----------------+
176 |Standard | See below. |
177 +--------------------+-----------------+
178
179
180 For utimes(), utimensat() and futimensat(), see standards(5).
181
182 SEE ALSO
183 futimens(2), stat(2), utime(2), attributes(5), fsattr(5), standards(5)
184
185
186
187 December 20, 2014 UTIMES(2)
|
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
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)
|