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
123
124 ENAMETOOLONG
125 The length of the path argument exceeds {PATH_MAX} or a
126 pathname component is longer than {NAME_MAX}.
127
128
129 ENOLINK
130 The path argument points to a remote machine and the
131 link to that machine is no longer active.
132
133
134 ENOENT
135 A component of path does not name an existing file or
136 path is an empty string.
137
138
139 ENOTDIR
140 A component of the path prefix is not a directory or
141 the path argument is relative and the fildes argument
142 is not AT_FDCWD or does not refer to a valid directory.
143
144
145 EPERM
146 The times argument is not a null pointer and the
147 calling process's effective user ID has write access to
148 the file but does not match the owner of the file and
149 the calling process does not have the appropriate
150 privileges.
151
152
153 EROFS
154 The file system containing the file is read-only.
155
156
157
158 The utimes(), futimesat(), and utimensat() functions may fail if:
159
160 ENAMETOOLONG
161 Path name resolution of a symbolic link produced an
162 intermediate result whose length exceeds {PATH_MAX}.
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)