]>
Commit | Line | Data |
---|---|---|
61dd016f MK |
1 | .\" Hey Emacs! This file is -*- nroff -*- source. |
2 | .\" | |
3 | .\" Copyright (C) 2008, Linux Foundation, written by Michael Kerrisk | |
4 | .\" <mtk.manpages@gmail.com> | |
5 | .\" | |
6 | .\" Permission is granted to make and distribute verbatim copies of this | |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
14 | .\" | |
15 | .\" Since the Linux kernel and libraries are constantly changing, this | |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
22 | .\" | |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
25 | .\" | |
7cc796ee | 26 | .TH UTIMENSAT 2 2009-12-13 "Linux" "Linux Programmer's Manual" |
61dd016f MK |
27 | .SH NAME |
28 | utimensat, futimens \- change file timestamps with nanosecond precision | |
61dd016f MK |
29 | .SH SYNOPSIS |
30 | .nf | |
31 | .B #include <sys/stat.h> | |
32 | .sp | |
33 | .BI "int utimensat(int " dirfd ", const char *" pathname , | |
34 | .BI " const struct timespec " times "[2], int " flags ); | |
35 | ||
36 | .BI "int futimens(int " fd ", const struct timespec " times [2]); | |
37 | .fi | |
38 | .sp | |
39 | .in -4n | |
40 | Feature Test Macro Requirements for glibc (see | |
41 | .BR feature_test_macros (7)): | |
42 | .in | |
43 | .sp | |
44 | .BR utimensat (): | |
7cc796ee MK |
45 | .br |
46 | Since glibc 2.10: _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L | |
47 | .br | |
48 | Before glibc 2.10: | |
61dd016f MK |
49 | _ATFILE_SOURCE |
50 | .br | |
51 | .BR futimens (): | |
7cc796ee MK |
52 | .br |
53 | Since glibc 2.10: _XOPEN_SOURCE >= 700 || _POSIX_C_SOURCE >= 200809L | |
54 | .br | |
55 | Before glibc 2.10: | |
56 | _GNU_SOURCE | |
61dd016f MK |
57 | .SH DESCRIPTION |
58 | .BR utimensat () | |
59 | and | |
60 | .BR futimens () | |
61 | update the timestamps of a file with nanosecond precision. | |
62 | This contrasts with the historical | |
63 | .BR utime (2) | |
64 | and | |
65 | .BR utimes (2), | |
66 | which permit only second and microsecond precision, respectively, | |
67 | when setting file timestamps. | |
68 | ||
69 | With | |
70 | .BR utimensat () | |
71 | the file is specified via the pathname given in | |
72 | .IR pathname . | |
73 | With | |
74 | .BR futimens () | |
75 | the file whose timestamps are to be updated is specified via | |
76 | an open file descriptor, | |
77 | .IR fd . | |
78 | ||
79 | For both calls, the new file timestamps are specified in the array | |
80 | .IR times : | |
81 | .IR times [0] | |
82 | specifies the new "last access time" (\fIatime\fP); | |
83 | .IR times [1] | |
84 | specifies the new "last modification time" (\fImtime\fP). | |
85 | Each of the elements of | |
86 | .I times | |
87 | specifies a time in seconds and nanoseconds | |
88 | since the Epoch (00:00:00, 1 Jan 1970, UTC), | |
89 | in a structure of the following form: | |
90 | .in +4n | |
91 | .nf | |
92 | ||
93 | struct timespec { | |
94 | time_t tv_sec; /* seconds */ | |
95 | long tv_nsec; /* nanoseconds */ | |
96 | }; | |
97 | .fi | |
98 | .in | |
99 | .PP | |
100 | Updated file timestamps are set to the greatest value | |
101 | supported by the file system that is not greater than the specified time. | |
102 | ||
103 | If the | |
104 | .I tv_nsec | |
105 | field of one of the | |
106 | .I timespec | |
107 | structures has the special value | |
108 | .BR UTIME_NOW , | |
109 | then the corresponding file timestamp is set to the current time. | |
110 | If the | |
111 | .I tv_nsec | |
112 | field of one of the | |
113 | .I timespec | |
114 | structures has the special value | |
115 | .BR UTIME_OMIT , | |
116 | then the corresponding file timestamp is left unchanged. | |
117 | In both of these cases, the value of the corresponding | |
118 | .I tv_sec | |
119 | .\" 2.6.22 was broken: it is not ignored | |
120 | field is ignored. | |
121 | ||
122 | If | |
123 | .I times | |
124 | is NULL, then both timestamps are set to the current time. | |
125 | .\" | |
126 | .SS Permissions requirements | |
127 | To set both file timestamps to the current time (i.e., | |
128 | .I times | |
129 | is NULL, or both | |
130 | .I tv_nsec | |
131 | fields specify | |
132 | .BR UTIME_NOW ), | |
133 | either: | |
134 | .IP 1. 3 | |
135 | the caller must have write access to the file; | |
136 | .\" 2.6.22 was broken here -- for futimens() the check is | |
137 | .\" based on whether or not the file descriptor is writable, | |
138 | .\" not on whether the the caller's effective UID has write | |
139 | .\" permission for the file referred to by the descriptor. | |
140 | .IP 2. | |
141 | the caller's effective user ID must match the owner of the file; or | |
142 | .IP 3. | |
143 | the caller must have appropriate privileges. | |
144 | .PP | |
145 | To make any change other than setting both timestamps to the | |
146 | current time (i.e., | |
147 | .I times | |
148 | is not NULL, and both | |
149 | .I tv_nsec | |
150 | fields are not | |
151 | .B UTIME_NOW | |
152 | .\" 2.6.22 was broken here: | |
153 | .\" both must something other than *either* UTIME_OMIT *or* UTIME_NOW. | |
154 | and both | |
155 | .I tv_nsec | |
156 | fields are not | |
157 | .BR UTIME_OMIT ), | |
158 | either condition 2 or 3 above must apply. | |
159 | ||
160 | If both | |
161 | .I tv_nsec | |
162 | fields are specified as | |
163 | .BR UTIME_OMIT , | |
164 | then no file ownership or permission checks are performed, | |
165 | and the file timestamps are not modified, | |
166 | but other error conditions may still be detected. | |
167 | .\" | |
168 | .\" | |
169 | .SS utimensat() specifics | |
170 | If | |
171 | .I pathname | |
172 | is relative, then by default it is interpreted relative to the | |
173 | directory referred to by the open file descriptor, | |
174 | .IR dirfd | |
175 | (rather than relative to the current working directory of | |
176 | the calling process, as is done by | |
177 | .BR utimes (2) | |
178 | for a relative pathname). | |
179 | See | |
180 | .BR openat (2) | |
181 | for an explanation of why this can be useful. | |
182 | .\" FIXME . Say something about O_SEARCH? (But it's not in current | |
183 | .\" glibc (Mar 08), or kernel 2.6.25.) | |
184 | ||
185 | If | |
186 | .I pathname | |
187 | is relative and | |
188 | .I dirfd | |
189 | is the special value | |
190 | .BR AT_FDCWD , | |
191 | then | |
192 | .I pathname | |
193 | is interpreted relative to the current working | |
194 | directory of the calling process (like | |
195 | .BR utimes (2)). | |
196 | ||
197 | If | |
198 | .I pathname | |
199 | is absolute, then | |
200 | .I dirfd | |
201 | is ignored. | |
202 | ||
203 | The | |
204 | .I flags | |
205 | field is a bit mask that may be 0, or include the following constant, | |
206 | defined in | |
207 | .IR <fcntl.h> : | |
208 | .TP | |
209 | .B AT_SYMLINK_NOFOLLOW | |
210 | If | |
211 | .I pathname | |
212 | specifies a symbolic link, then update the timestamps of the link, | |
213 | rather than the file to which it refers. | |
214 | .SH "RETURN VALUE" | |
215 | On success, | |
216 | .BR utimensat () | |
217 | and | |
218 | .BR futimens () | |
219 | return 0. | |
220 | On error, \-1 is returned and | |
221 | .I errno | |
222 | is set to indicate the error. | |
223 | .SH ERRORS | |
224 | .TP | |
225 | .B EACCES | |
226 | .I times | |
227 | is NULL, | |
228 | or both | |
229 | .I tv_nsec | |
230 | values are | |
231 | .BR UTIME_NOW , | |
232 | and: | |
233 | .PD 0 | |
234 | .RS | |
235 | .IP * 2 | |