]>
Commit | Line | Data |
---|---|---|
9905e59b DH |
1 | '\" t |
2 | .\" Copyright (c) 2017 David Howells <dhowells@redhat.com> | |
3 | .\" | |
4 | .\" Derived from the stat.2 manual page: | |
5 | .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 | |
6 | .\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95 | |
7 | .\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com> | |
8 | .\" | |
9 | .\" %%%LICENSE_START(VERBATIM) | |
10 | .\" Permission is granted to make and distribute verbatim copies of this | |
11 | .\" manual provided the copyright notice and this permission notice are | |
12 | .\" preserved on all copies. | |
13 | .\" | |
14 | .\" Permission is granted to copy and distribute modified versions of this | |
15 | .\" manual under the conditions for verbatim copying, provided that the | |
16 | .\" entire resulting derived work is distributed under the terms of a | |
17 | .\" permission notice identical to this one. | |
18 | .\" | |
19 | .\" Since the Linux kernel and libraries are constantly changing, this | |
20 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
21 | .\" responsibility for errors or omissions, or for damages resulting from | |
22 | .\" the use of the information contained herein. The author(s) may not | |
23 | .\" have taken the same level of care in the production of this manual, | |
24 | .\" which is licensed free of charge, as they might when working | |
25 | .\" professionally. | |
26 | .\" | |
27 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
28 | .\" the source, must acknowledge the copyright and authors of this work. | |
29 | .\" %%%LICENSE_END | |
30 | .\" | |
31 | .TH STATX 2 2017-03-07 "Linux" "Linux Programmer's Manual" | |
32 | .SH NAME | |
835f4293 | 33 | statx \- get file status (extended) |
9905e59b DH |
34 | .SH SYNOPSIS |
35 | .nf | |
36 | .B #include <sys/types.h> | |
9905e59b | 37 | .B #include <sys/stat.h> |
9905e59b | 38 | .B #include <unistd.h> |
9905e59b | 39 | .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" |
835f4293 | 40 | |
9905e59b DH |
41 | .BI "int statx(int " dirfd ", const char *" pathname ", int " flags "," |
42 | .BI " unsigned int " mask ", struct statx *" buf ); | |
43 | .fi | |
44 | .sp | |
45 | .in -4n | |
46 | Feature Test Macro Requirements for glibc (see | |
47 | .BR feature_test_macros (7)): | |
48 | .in | |
49 | .ad l | |
50 | .PD 0 | |
51 | .sp | |
52 | .RS 4 | |
53 | <unknown as yet> | |
54 | .RE | |
55 | .PD | |
56 | .ad | |
57 | .SH DESCRIPTION | |
58 | .PP | |
59 | This function returns information about a file, storing it in the buffer | |
60 | pointed to by | |
61 | .IR buf . | |
62 | The buffer is filled in according to the following type: | |
63 | .PP | |
64 | .in +4n | |
65 | .nf | |
66 | struct statx { | |
77a09ad7 MK |
67 | __u32 stx_mask; /* Mask of bits indicating |
68 | filled fields */ | |
69 | __u32 stx_blksize; /* Block size for filesystem I/O */ | |
70 | __u64 stx_attributes; /* Extra file attribute indicators */ | |
71 | __u32 stx_nlink; /* Number of hard links */ | |
72 | __u32 stx_uid; /* User ID of owner */ | |
73 | __u32 stx_gid; /* Group ID of owner */ | |
74 | __u16 stx_mode; /* File type and mode */ | |
75 | __u64 stx_ino; /* Inode number */ | |
76 | __u64 stx_size; /* Total size in bytes */ | |
77 | __u64 stx_blocks; /* Number of 512B blocks allocated */ | |
6a4667aa MK |
78 | |
79 | /* The following fields are file timestamps */ | |
80 | struct statx_timestamp stx_atime; /* Last access */ | |
81 | struct statx_timestamp stx_btime; /* Creation */ | |
82 | struct statx_timestamp stx_ctime; /* Last status change */ | |
83 | struct statx_timestamp stx_mtime; /* Last modification */ | |
84 | ||
108cd6a3 | 85 | /* If this file represents device, then the next two fields |
6a4667aa | 86 | contain the ID of the device */ |
77a09ad7 MK |
87 | __u32 stx_rdev_major; /* Major ID */ |
88 | __u32 stx_rdev_minor; /* Minor ID */ | |
6a4667aa MK |
89 | |
90 | /* The next two fields contain the ID of the device | |
91 | contain the filesystem where the file resides */ | |
77a09ad7 MK |
92 | __u32 stx_dev_major; /* Major ID */ |
93 | __u32 stx_dev_minor; /* Minor ID */ | |
9905e59b DH |
94 | }; |
95 | .fi | |
96 | .in | |
97 | .PP | |
6a4667aa | 98 | The file timestamps are structures of the following type: |
9905e59b DH |
99 | .PP |
100 | .in +4n | |
101 | .nf | |
102 | struct statx_timestamp { | |
6a4667aa MK |
103 | __s64 tv_sec; /* Seconds since the Epoch (UNIX time) */ |
104 | __s32 tv_nsec; /* Nanoseconds before or since tv_sec */ | |
9905e59b DH |
105 | }; |
106 | .fi | |
107 | .in | |
108 | .PP | |
109 | (Note that reserved space and padding is omitted) | |
110 | .SS | |
111 | Invoking \fBstatx\fR(): | |
112 | .PP | |
14b5d02a MK |
113 | To access a file's status, no permissions are required on the file itself, |
114 | but in the case of | |
9905e59b | 115 | .BR statx () |
835f4293 | 116 | with a pathname, |
14b5d02a | 117 | execute (search) permission is required on all of the directories in |
9905e59b DH |
118 | .I pathname |
119 | that lead to the file. | |
120 | .PP | |
121 | .BR statx () | |
122 | uses | |
6a4667aa MK |
123 | .IR pathname , |
124 | .IR dirfd , | |
125 | and | |
126 | .IR flags | |
9905e59b DH |
127 | to locate the target file in one of a variety of ways: |
128 | .TP | |
835f4293 | 129 | [*] By absolute pathname. |
9905e59b | 130 | .I pathname |
835f4293 | 131 | points to an absolute pathname and |
9905e59b | 132 | .I dirfd |
14b5d02a MK |
133 | is ignored. |
134 | The file is looked up by name, starting from the root of the | |
9905e59b DH |
135 | filesystem as seen by the calling process. |
136 | .TP | |
835f4293 | 137 | [*] By cwd-relative pathname. |
9905e59b | 138 | .I pathname |
835f4293 | 139 | points to a relative pathname and |
6a4667aa MK |
140 | .IR dirfd |
141 | is | |
142 | .BR AT_FDCWD . | |
9905e59b DH |
143 | The file is looked up by name, starting from the current working directory. |
144 | .TP | |
835f4293 | 145 | [*] By dir-relative pathname. |
9905e59b | 146 | .I pathname |
835f4293 | 147 | points to relative pathname and |
9905e59b | 148 | .I dirfd |
14b5d02a MK |
149 | indicates a file descriptor pointing to a directory. |
150 | The file is looked up by name, starting from the directory specified by | |
9905e59b DH |
151 | .IR dirfd . |
152 | .TP | |
153 | [*] By file descriptor. | |
77a09ad7 MK |
154 | .IR pathname |
155 | is NULL and | |
156 | .I dirfd | |
14b5d02a MK |
157 | indicates a file descriptor. |
158 | The file attached to the file descriptor is queried directly. | |
159 | The file descriptor may point to any type of file, not just | |
9905e59b DH |
160 | a directory. |
161 | .PP | |
162 | .I flags | |
835f4293 | 163 | can be used to influence a pathname-based lookup. |
14b5d02a | 164 | A value for |
9905e59b DH |
165 | .I flags |
166 | is constructed by OR'ing together zero or more of the following constants: | |
167 | .TP | |
168 | .BR AT_EMPTY_PATH | |
169 | .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d | |
170 | If | |
171 | .I pathname | |
172 | is an empty string, operate on the file referred to by | |
173 | .IR dirfd | |
174 | (which may have been obtained using the | |
175 | .BR open (2) | |
176 | .B O_PATH | |
177 | flag). | |
178 | If | |
179 | .I dirfd | |
180 | is | |
181 | .BR AT_FDCWD , | |
182 | the call operates on the current working directory. | |
183 | In this case, | |
184 | .I dirfd | |
185 | can refer to any type of file, not just a directory. | |
186 | This flag is Linux-specific; define | |
187 | .B _GNU_SOURCE | |
188 | .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed | |
189 | to obtain its definition. | |
190 | .TP | |
191 | .BR AT_NO_AUTOMOUNT | |
192 | Don't automount the terminal ("basename") component of | |
193 | .I pathname | |
194 | if it is a directory that is an automount point. | |
195 | This allows the caller to gather attributes of an automount point | |
196 | (rather than the location it would mount). | |
197 | This flag can be used in tools that scan directories | |
198 | to prevent mass-automounting of a directory of automount points. | |
199 | The | |
200 | .B AT_NO_AUTOMOUNT | |
201 | flag has no effect if the mount point has already been mounted over. | |
202 | This flag is Linux-specific; define | |
203 | .B _GNU_SOURCE | |
204 | .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed | |
205 | to obtain its definition. | |
206 | .TP | |
207 | .B AT_SYMLINK_NOFOLLOW | |
208 | If | |
209 | .I pathname | |
210 | is a symbolic link, do not dereference it: | |
211 | instead return information about the link itself, like | |
6a4667aa | 212 | .BR lstat (2). |
9905e59b DH |
213 | .PP |
214 | .I flags | |
14b5d02a MK |
215 | can also be used to control what sort of synchronization the kernel will do |
216 | when querying a file on a remote filesystem. | |
217 | This is done by OR'ing in one of the following values: | |
9905e59b | 218 | .TP |
709f7bb6 | 219 | .B AT_STATX_SYNC_AS_STAT |
9905e59b | 220 | Do whatever |
6a4667aa | 221 | .BR stat (2) |
14b5d02a MK |
222 | does. |
223 | This is the default and is very much filesystem specific. | |
9905e59b | 224 | .TP |
709f7bb6 | 225 | .B AT_STATX_FORCE_SYNC |
46711e96 | 226 | Force the attributes to be synchronized with the server. |
14b5d02a | 227 | This may require that |
9905e59b DH |
228 | a network filesystem perform a data writeback to get the timestamps correct. |
229 | .TP | |
709f7bb6 | 230 | .B AT_STATX_DONT_SYNC |
46711e96 | 231 | Don't synchronize anything, but rather just take whatever |
ffe297ee | 232 | the system has cached if possible. |
14b5d02a | 233 | This may mean that the information returned is approximate, but, |
9905e59b DH |
234 | on a network filesystem, it may not involve a round trip to the server - even |
235 | if no lease is held. | |
236 | .PP | |
237 | The | |
238 | .I mask | |
239 | argument to | |
240 | .BR statx () | |
241 | is used to tell the kernel which fields the caller is interested in. | |
242 | .I mask | |
243 | is an OR'ed combination of the following constants: | |
244 | .PP | |
245 | .in +4n | |
246 | .TS | |
247 | lB l. | |
248 | STATX_TYPE Want stx_mode & S_IFMT | |
249 | STATX_MODE Want stx_mode & ~S_IFMT | |
250 | STATX_NLINK Want stx_nlink | |
251 | STATX_UID Want stx_uid | |
252 | STATX_GID Want stx_gid | |
253 | STATX_ATIME Want stx_atime{,_ns} | |
254 | STATX_MTIME Want stx_mtime{,_ns} | |
255 | STATX_CTIME Want stx_ctime{,_ns} | |
256 | STATX_INO Want stx_ino | |
257 | STATX_SIZE Want stx_size | |
258 | STATX_BLOCKS Want stx_blocks | |
259 | STATX_BASIC_STATS [All of the above] | |
260 | STATX_BTIME Want stx_btime{,_ns} | |
261 | STATX_ALL [All currently available fields] | |
262 | .TE | |
263 | .in | |
264 | .PP | |
265 | .B "Do not" | |
266 | simply set | |
267 | .I mask | |
709f7bb6 MK |
268 | to |
269 | .B UINT_MAX | |
270 | as one or more bits may, in the future, be used to specify an | |
9905e59b DH |
271 | extension to the buffer. |
272 | .SS | |
273 | The returned information | |
274 | .PP | |
275 | The status information for the target file is returned in the | |
276 | .I statx | |
277 | structure pointed to by | |
278 | .IR buf . | |
279 | Included in this is | |
280 | .I stx_mask | |
281 | which indicates what other information has been returned. | |
282 | .I stx_mask | |
283 | has the same format as the mask argument and bits are set in it to indicate | |
284 | which fields have been filled in. | |
285 | .PP | |
ffe297ee MK |
286 | It should be noted that the kernel may return fields that weren't |
287 | requested and may fail to return fields that were requested, | |
288 | depending on what the backing filesystem supports. | |
14b5d02a | 289 | In either case, |
9905e59b DH |
290 | .I stx_mask |
291 | will not be equal | |
292 | .IR mask . | |
293 | .PP | |
ffe297ee MK |
294 | If a filesystem does not support a field or if it has |
295 | an unrepresentable value (for instance, a file with an exotic type), | |
296 | then the mask bit corresponding to that field will be cleared in | |
9905e59b DH |
297 | .I stx_mask |
298 | even if the user asked for it and a dummy value will be filled in for | |
835f4293 | 299 | compatibility purposes if one is available (e.g., a dummy UID and GID may be |
9905e59b DH |
300 | specified to mount under some circumstances). |
301 | .PP | |
302 | A filesystem may also fill in fields that the caller didn't ask for if it has | |
835f4293 | 303 | values for them available and the information is available at no extra cost. |
14b5d02a | 304 | If this happens, the corresponding bits will be set in |
9905e59b DH |
305 | .IR stx_mask . |
306 | .PP | |
9905e59b DH |
307 | .\" Background: inode attributes are modified with i_mutex held, but |
308 | .\" read by stat() without taking the mutex. | |
835f4293 MK |
309 | .IR Note : |
310 | for performance and simplicity reasons, different fields in the | |
9905e59b DH |
311 | .I statx |
312 | structure may contain state information from different moments | |
313 | during the execution of the system call. | |
314 | For example, if | |
315 | .IR stx_mode | |
316 | or | |
317 | .IR stx_uid | |
318 | is changed by another process by calling | |
319 | .BR chmod (2) | |
320 | or | |
321 | .BR chown (2), | |
322 | .BR stat () | |
323 | might return the old | |
324 | .I stx_mode | |
325 | together with the new | |
326 | .IR stx_uid , | |
327 | or the old | |
328 | .I stx_uid | |
329 | together with the new | |
330 | .IR stx_mode . | |
331 | .PP | |
77a09ad7 MK |
332 | Apart from |
333 | .I stx_mask | |
334 | (which is described above), the fields in the | |
9905e59b DH |
335 | .I statx |
336 | structure are: | |
337 | .TP | |
338 | .I stx_mode | |
14b5d02a | 339 | The file type and mode. |
19cda35d MK |
340 | See |
341 | .BR inode (7) | |
342 | for details. | |
9905e59b DH |
343 | .TP |
344 | .I stx_size | |
345 | The size of the file (if it is a regular file or a symbolic link) in bytes. | |
ffe297ee MK |
346 | The size of a symbolic link is the length of the pathname it contains, |
347 | without a terminating null byte. | |
9905e59b DH |
348 | .TP |
349 | .I stx_blocks | |
350 | The number of blocks allocated to the file on the medium, in 512-byte units. | |
351 | (This may be smaller than | |
352 | .IR stx_size /512 | |
353 | when the file has holes.) | |
354 | .TP | |
355 | .I stx_blksize | |
835f4293 | 356 | The "preferred" block size for efficient filesystem I/O. |
14b5d02a | 357 | (Writing to a file in |
9905e59b DH |
358 | smaller chunks may cause an inefficient read-modify-rewrite.) |
359 | .TP | |
360 | .I stx_nlink | |
361 | The number of hard links on a file. | |
362 | .TP | |
363 | .I stx_uid | |
364 | The user ID of the file's owner. | |
365 | .TP | |
366 | .I stx_gid | |
367 | The ID of the group that may access the file. | |
368 | .TP | |
369 | .IR stx_dev_major " and " stx_dev_minor | |
370 | The device on which this file (inode) resides. | |
371 | .TP | |
372 | .IR stx_rdev_major " and " stx_rdev_minor | |
373 | The device that this file (inode) represents if the file is of block or | |
374 | character device type. | |
375 | .TP | |
376 | .I stx_attributes | |
377 | Further status information about the file (see below for more information). | |
378 | .TP | |
379 | .I stx_atime | |
380 | The file's last access timestamp. | |
9905e59b DH |
381 | .TP |
382 | .I stx_btime | |
14b5d02a | 383 | The file's creation timestamp. |
9905e59b DH |
384 | .TP |
385 | .I stx_ctime | |
14b5d02a | 386 | The file's last status change timestamp. |
9905e59b DH |
387 | .TP |
388 | .I stx_mtime | |
14b5d02a | 389 | The file's last modification timestamp. |
9905e59b | 390 | .PP |
19cda35d MK |
391 | For further information on the above fields, see |
392 | .BR inode (7). | |
14b5d02a | 393 | .\" |
9905e59b DH |
394 | .SS File attributes |
395 | .PP | |
396 | The | |
397 | .I stx_attributes | |
ffe297ee MK |
398 | field contains a set of OR'ed flags that indicate additional attributes |
399 | of the file: | |
9905e59b | 400 | .TP |
77a09ad7 | 401 | .B STATX_ATTR_COMPRESSED |
9905e59b DH |
402 | The file is compressed by the fs and may take extra resources to access. |
403 | .TP | |
77a09ad7 | 404 | .B STATX_ATTR_IMMUTABLE |
ffe297ee MK |
405 | The file cannot be modified: it cannot be deleted or renamed, |
406 | no hard links can be created to this file and no data can be written to it. | |
709f7bb6 MK |
407 | See |
408 | .BR chattr (1). | |
9905e59b | 409 | .TP |
77a09ad7 | 410 | .B STATX_ATTR_APPEND |
14b5d02a MK |
411 | The file can only be opened in append mode for writing. |
412 | Random access writing | |
413 | is not permitted. | |
709f7bb6 MK |
414 | See |
415 | .BR chattr (1). | |
9905e59b | 416 | .TP |
77a09ad7 | 417 | .B STATX_ATTR_NODUMP |
709f7bb6 MK |
418 | File is not a candidate for backup when a backup program such as |
419 | .BR dump (8) | |
420 | is run. | |
421 | See | |
422 | .BR chattr (1). | |
9905e59b | 423 | .TP |
77a09ad7 | 424 | .B STATX_ATTR_ENCRYPTED |
9905e59b | 425 | A key is required for the file to be encrypted by the filesystem. |
9905e59b DH |
426 | .SH RETURN VALUE |
427 | On success, zero is returned. | |
428 | On error, \-1 is returned, and | |
429 | .I errno | |
430 | is set appropriately. | |
431 | .SH ERRORS | |
432 | .TP | |
433 | .B EINVAL | |
434 | Invalid flag specified in | |
435 | .IR flags . | |
436 | .TP | |
437 | .B EACCES | |
438 | Search permission is denied for one of the directories | |
439 | in the path prefix of | |
440 | .IR pathname . | |
441 | (See also | |
442 | .BR path_resolution (7).) | |
443 | .TP | |
444 | .B EBADF | |
445 | .I dirfd | |
446 | is not a valid open file descriptor. | |
447 | .TP | |
448 | .B EFAULT | |
449 | Bad address. | |
450 | .TP | |
451 | .B ELOOP | |
835f4293 | 452 | Too many symbolic links encountered while traversing the pathname. |
9905e59b DH |
453 | .TP |
454 | .B ENAMETOOLONG | |
455 | .I pathname | |
456 | is too long. | |
457 | .TP | |
458 | .B ENOENT | |
459 | A component of | |
460 | .I pathname | |
461 | does not exist, or | |
462 | .I pathname | |
463 | is an empty string and AT_EMPTY_PATH was not specified. | |
464 | .TP | |
465 | .B ENOMEM | |
466 | Out of memory (i.e., kernel memory). | |
467 | .TP | |
468 | .B ENOTDIR | |
469 | A component of the path prefix of | |
470 | .I pathname | |
471 | is not a directory or | |
472 | .I pathname | |
473 | is relative and | |
474 | .I dirfd | |
475 | is a file descriptor referring to a file other than a directory. | |
476 | .SH VERSIONS | |
477 | .BR statx () | |
478 | was added to Linux in kernel 4.11; | |
479 | library support is not yet added to glibc. | |
480 | .SH SEE ALSO | |
481 | .BR ls (1), | |
482 | .BR stat (1), | |
483 | .BR access (2), | |
484 | .BR chmod (2), | |
485 | .BR chown (2), | |
486 | .BR stat (2), | |
487 | .BR readlink (2), | |
488 | .BR utime (2), | |
489 | .BR capabilities (7), | |
490 | .BR symlink (7) |