]>
Commit | Line | Data |
---|---|---|
a1eaacb1 | 1 | '\" t |
9905e59b DH |
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 | .\" | |
5fbde956 | 9 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
9905e59b | 10 | .\" |
4c1c5274 | 11 | .TH statx 2 (date) "Linux man-pages (unreleased)" |
9905e59b | 12 | .SH NAME |
835f4293 | 13 | statx \- get file status (extended) |
13e949d8 AC |
14 | .SH LIBRARY |
15 | Standard C library | |
8fc3b2cf | 16 | .RI ( libc ", " \-lc ) |
9905e59b DH |
17 | .SH SYNOPSIS |
18 | .nf | |
b4e16396 | 19 | .BR "#define _GNU_SOURCE " "/* See feature_test_macros(7) */" |
c9f3f849 | 20 | .BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */" |
9905e59b | 21 | .B #include <sys/stat.h> |
dbfe9c70 | 22 | .PP |
049d7f92 AC |
23 | .BI "int statx(int " dirfd ", const char *restrict " pathname ", int " flags , |
24 | .BI " unsigned int " mask ", struct statx *restrict " statxbuf ); | |
9905e59b | 25 | .fi |
9905e59b | 26 | .SH DESCRIPTION |
9905e59b DH |
27 | This function returns information about a file, storing it in the buffer |
28 | pointed to by | |
15d1f5ac | 29 | .IR statxbuf . |
c8701baf | 30 | The returned buffer is a structure of the following type: |
9905e59b DH |
31 | .PP |
32 | .in +4n | |
b8302363 | 33 | .EX |
9905e59b | 34 | struct statx { |
115b4e0e AC |
35 | __u32 stx_mask; /* Mask of bits indicating |
36 | filled fields */ | |
37 | __u32 stx_blksize; /* Block size for filesystem I/O */ | |
38 | __u64 stx_attributes; /* Extra file attribute indicators */ | |
39 | __u32 stx_nlink; /* Number of hard links */ | |
40 | __u32 stx_uid; /* User ID of owner */ | |
41 | __u32 stx_gid; /* Group ID of owner */ | |
42 | __u16 stx_mode; /* File type and mode */ | |
43 | __u64 stx_ino; /* Inode number */ | |
44 | __u64 stx_size; /* Total size in bytes */ | |
45 | __u64 stx_blocks; /* Number of 512B blocks allocated */ | |
46 | __u64 stx_attributes_mask; | |
b957f81f | 47 | /* Mask to show what\[aq]s supported |
115b4e0e | 48 | in stx_attributes */ |
6a4667aa MK |
49 | |
50 | /* The following fields are file timestamps */ | |
51 | struct statx_timestamp stx_atime; /* Last access */ | |
52 | struct statx_timestamp stx_btime; /* Creation */ | |
53 | struct statx_timestamp stx_ctime; /* Last status change */ | |
54 | struct statx_timestamp stx_mtime; /* Last modification */ | |
55 | ||
20c8cd9a MK |
56 | /* If this file represents a device, then the next two |
57 | fields contain the ID of the device */ | |
115b4e0e AC |
58 | __u32 stx_rdev_major; /* Major ID */ |
59 | __u32 stx_rdev_minor; /* Minor ID */ | |
6a4667aa MK |
60 | |
61 | /* The next two fields contain the ID of the device | |
790314d7 | 62 | containing the filesystem where the file resides */ |
115b4e0e AC |
63 | __u32 stx_dev_major; /* Major ID */ |
64 | __u32 stx_dev_minor; /* Minor ID */ | |
ed1cff15 | 65 | |
115b4e0e | 66 | __u64 stx_mnt_id; /* Mount ID */ |
ed1cff15 EB |
67 | |
68 | /* Direct I/O alignment restrictions */ | |
69 | __u32 stx_dio_mem_align; | |
70 | __u32 stx_dio_offset_align; | |
9905e59b | 71 | }; |
b8302363 | 72 | .EE |
9905e59b DH |
73 | .in |
74 | .PP | |
6a4667aa | 75 | The file timestamps are structures of the following type: |
9905e59b DH |
76 | .PP |
77 | .in +4n | |
b8302363 | 78 | .EX |
9905e59b | 79 | struct statx_timestamp { |
115b4e0e AC |
80 | __s64 tv_sec; /* Seconds since the Epoch (UNIX time) */ |
81 | __u32 tv_nsec; /* Nanoseconds since tv_sec */ | |
9905e59b | 82 | }; |
b8302363 | 83 | .EE |
9905e59b DH |
84 | .in |
85 | .PP | |
790314d7 | 86 | (Note that reserved space and padding is omitted.) |
9905e59b DH |
87 | .SS |
88 | Invoking \fBstatx\fR(): | |
14b5d02a MK |
89 | To access a file's status, no permissions are required on the file itself, |
90 | but in the case of | |
9905e59b | 91 | .BR statx () |
835f4293 | 92 | with a pathname, |
14b5d02a | 93 | execute (search) permission is required on all of the directories in |
9905e59b DH |
94 | .I pathname |
95 | that lead to the file. | |
96 | .PP | |
97 | .BR statx () | |
98 | uses | |
6a4667aa MK |
99 | .IR pathname , |
100 | .IR dirfd , | |
101 | and | |
1ae6b2c7 | 102 | .I flags |
56a05af6 | 103 | to identify the target file in one of the following ways: |
9905e59b | 104 | .TP |
7e43caf4 MK |
105 | An absolute pathname |
106 | If | |
9905e59b | 107 | .I pathname |
7e43caf4 MK |
108 | begins with a slash, |
109 | then it is an absolute pathname that identifies the target file. | |
110 | In this case, | |
9905e59b | 111 | .I dirfd |
14b5d02a | 112 | is ignored. |
9905e59b | 113 | .TP |
7e43caf4 MK |
114 | A relative pathname |
115 | If | |
9905e59b | 116 | .I pathname |
7e43caf4 | 117 | is a string that begins with a character other than a slash and |
1ae6b2c7 | 118 | .I dirfd |
6a4667aa | 119 | is |
7e43caf4 MK |
120 | .BR AT_FDCWD , |
121 | then | |
122 | .I pathname | |
123 | is a relative pathname that is interpreted relative to the process's | |
124 | current working directory. | |
9905e59b | 125 | .TP |
aabbefb4 | 126 | A directory-relative pathname |
7e43caf4 | 127 | If |
9905e59b | 128 | .I pathname |
7e43caf4 | 129 | is a string that begins with a character other than a slash and |
9905e59b | 130 | .I dirfd |
7e43caf4 MK |
131 | is a file descriptor that refers to a directory, then |
132 | .I pathname | |
133 | is a relative pathname that is interpreted relative to the directory | |
134 | referred to by | |
9905e59b | 135 | .IR dirfd . |
717c3a7d MK |
136 | (See |
137 | .BR openat (2) | |
138 | for an explanation of why this is useful.) | |
9905e59b | 139 | .TP |
7e43caf4 MK |
140 | By file descriptor |
141 | If | |
1ae6b2c7 | 142 | .I pathname |
85dbf7cd | 143 | is an empty string and the |
7e43caf4 | 144 | .B AT_EMPTY_PATH |
85dbf7cd | 145 | flag is specified in |
1ae6b2c7 | 146 | .I flags |
85dbf7cd MK |
147 | (see below), |
148 | then the target file is the one referred to by the file descriptor | |
149 | .IR dirfd . | |
9905e59b DH |
150 | .PP |
151 | .I flags | |
835f4293 | 152 | can be used to influence a pathname-based lookup. |
14b5d02a | 153 | A value for |
9905e59b | 154 | .I flags |
c8701baf | 155 | is constructed by ORing together zero or more of the following constants: |
9905e59b | 156 | .TP |
1ae6b2c7 | 157 | .B AT_EMPTY_PATH |
9905e59b DH |
158 | .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d |
159 | If | |
160 | .I pathname | |
161 | is an empty string, operate on the file referred to by | |
1ae6b2c7 | 162 | .I dirfd |
9905e59b DH |
163 | (which may have been obtained using the |
164 | .BR open (2) | |
165 | .B O_PATH | |
166 | flag). | |
85dbf7cd MK |
167 | In this case, |
168 | .I dirfd | |
169 | can refer to any type of file, not just a directory. | |
efeece04 | 170 | .IP |
9905e59b DH |
171 | If |
172 | .I dirfd | |
173 | is | |
174 | .BR AT_FDCWD , | |
175 | the call operates on the current working directory. | |
9905e59b | 176 | .TP |
1ae6b2c7 | 177 | .B AT_NO_AUTOMOUNT |
9905e59b DH |
178 | Don't automount the terminal ("basename") component of |
179 | .I pathname | |
180 | if it is a directory that is an automount point. | |
181 | This allows the caller to gather attributes of an automount point | |
182 | (rather than the location it would mount). | |
b95fb0a5 PB |
183 | This flag has no effect if the mount point has already been mounted over. |
184 | .IP | |
9905e59b DH |
185 | The |
186 | .B AT_NO_AUTOMOUNT | |
b95fb0a5 PB |
187 | flag can be used in tools that scan directories |
188 | to prevent mass-automounting of a directory of automount points. | |
189 | .IP | |
190 | All of | |
191 | .BR stat (2), | |
192 | .BR lstat (2), | |
193 | and | |
194 | .BR fstatat (2) | |
195 | act as though | |
196 | .B AT_NO_AUTOMOUNT | |
197 | was set. | |
9905e59b DH |
198 | .TP |
199 | .B AT_SYMLINK_NOFOLLOW | |
200 | If | |
201 | .I pathname | |
202 | is a symbolic link, do not dereference it: | |
203 | instead return information about the link itself, like | |
6a4667aa | 204 | .BR lstat (2). |
9905e59b DH |
205 | .PP |
206 | .I flags | |
14b5d02a MK |
207 | can also be used to control what sort of synchronization the kernel will do |
208 | when querying a file on a remote filesystem. | |
c8701baf | 209 | This is done by ORing in one of the following values: |
9905e59b | 210 | .TP |
709f7bb6 | 211 | .B AT_STATX_SYNC_AS_STAT |
9905e59b | 212 | Do whatever |
6a4667aa | 213 | .BR stat (2) |
14b5d02a | 214 | does. |
56a05af6 | 215 | This is the default and is very much filesystem-specific. |
9905e59b | 216 | .TP |
709f7bb6 | 217 | .B AT_STATX_FORCE_SYNC |
46711e96 | 218 | Force the attributes to be synchronized with the server. |
14b5d02a | 219 | This may require that |
9905e59b DH |
220 | a network filesystem perform a data writeback to get the timestamps correct. |
221 | .TP | |
709f7bb6 | 222 | .B AT_STATX_DONT_SYNC |
46711e96 | 223 | Don't synchronize anything, but rather just take whatever |
ffe297ee | 224 | the system has cached if possible. |
14b5d02a | 225 | This may mean that the information returned is approximate, but, |
9905e59b DH |
226 | on a network filesystem, it may not involve a round trip to the server - even |
227 | if no lease is held. | |
228 | .PP | |
229 | The | |
230 | .I mask | |
231 | argument to | |
232 | .BR statx () | |
233 | is used to tell the kernel which fields the caller is interested in. | |
234 | .I mask | |
c8701baf | 235 | is an ORed combination of the following constants: |
9905e59b DH |
236 | .PP |
237 | .in +4n | |
238 | .TS | |
239 | lB l. | |
240 | STATX_TYPE Want stx_mode & S_IFMT | |
3f029bc9 | 241 | STATX_MODE Want stx_mode & \[ti]S_IFMT |
9905e59b DH |
242 | STATX_NLINK Want stx_nlink |
243 | STATX_UID Want stx_uid | |
244 | STATX_GID Want stx_gid | |
f4572b65 MK |
245 | STATX_ATIME Want stx_atime |
246 | STATX_MTIME Want stx_mtime | |
247 | STATX_CTIME Want stx_ctime | |
9905e59b DH |
248 | STATX_INO Want stx_ino |
249 | STATX_SIZE Want stx_size | |
250 | STATX_BLOCKS Want stx_blocks | |
251 | STATX_BASIC_STATS [All of the above] | |
f4572b65 | 252 | STATX_BTIME Want stx_btime |
81b33a55 EB |
253 | STATX_ALL The same as STATX_BASIC_STATS | STATX_BTIME. |
254 | It is deprecated and should not be used. | |
728009a4 | 255 | STATX_MNT_ID Want stx_mnt_id (since Linux 5.8) |
ed1cff15 EB |
256 | STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align |
257 | (since Linux 6.1; support varies by filesystem) | |
9905e59b DH |
258 | .TE |
259 | .in | |
260 | .PP | |
c031ffcc | 261 | Note that, in general, the kernel does |
393c5b58 MK |
262 | .I not |
263 | reject values in | |
264 | .I mask | |
265 | other than the above. | |
c031ffcc MK |
266 | (For an exception, see |
267 | .B EINVAL | |
268 | in errors.) | |
393c5b58 MK |
269 | Instead, it simply informs the caller which values are supported |
270 | by this kernel and filesystem via the | |
271 | .I statx.stx_mask | |
272 | field. | |
273 | Therefore, | |
274 | .I "do not" | |
9905e59b DH |
275 | simply set |
276 | .I mask | |
709f7bb6 MK |
277 | to |
278 | .B UINT_MAX | |
393c5b58 | 279 | (all bits set), |
709f7bb6 | 280 | as one or more bits may, in the future, be used to specify an |
9905e59b DH |
281 | extension to the buffer. |
282 | .SS | |
283 | The returned information | |
9905e59b DH |
284 | The status information for the target file is returned in the |
285 | .I statx | |
286 | structure pointed to by | |
15d1f5ac | 287 | .IR statxbuf . |
9905e59b DH |
288 | Included in this is |
289 | .I stx_mask | |
290 | which indicates what other information has been returned. | |
291 | .I stx_mask | |
790314d7 MK |
292 | has the same format as the |
293 | .I mask | |
294 | argument and bits are set in it to indicate | |
9905e59b DH |
295 | which fields have been filled in. |
296 | .PP | |
ffe297ee MK |
297 | It should be noted that the kernel may return fields that weren't |
298 | requested and may fail to return fields that were requested, | |
299 | depending on what the backing filesystem supports. | |
c859dfb5 | 300 | (Fields that are given values despite being unrequested can just be ignored.) |
14b5d02a | 301 | In either case, |
9905e59b DH |
302 | .I stx_mask |
303 | will not be equal | |
304 | .IR mask . | |
305 | .PP | |
ffe297ee MK |
306 | If a filesystem does not support a field or if it has |
307 | an unrepresentable value (for instance, a file with an exotic type), | |
308 | then the mask bit corresponding to that field will be cleared in | |
9905e59b DH |
309 | .I stx_mask |
310 | even if the user asked for it and a dummy value will be filled in for | |
835f4293 | 311 | compatibility purposes if one is available (e.g., a dummy UID and GID may be |
9905e59b DH |
312 | specified to mount under some circumstances). |
313 | .PP | |
314 | A filesystem may also fill in fields that the caller didn't ask for if it has | |
835f4293 | 315 | values for them available and the information is available at no extra cost. |
14b5d02a | 316 | If this happens, the corresponding bits will be set in |
9905e59b DH |
317 | .IR stx_mask . |
318 | .PP | |
9905e59b DH |
319 | .\" Background: inode attributes are modified with i_mutex held, but |
320 | .\" read by stat() without taking the mutex. | |
835f4293 MK |
321 | .IR Note : |
322 | for performance and simplicity reasons, different fields in the | |
9905e59b DH |
323 | .I statx |
324 | structure may contain state information from different moments | |
325 | during the execution of the system call. | |
326 | For example, if | |
1ae6b2c7 | 327 | .I stx_mode |
9905e59b | 328 | or |
1ae6b2c7 | 329 | .I stx_uid |
9905e59b DH |
330 | is changed by another process by calling |
331 | .BR chmod (2) | |
332 | or | |
333 | .BR chown (2), | |
334 | .BR stat () | |
335 | might return the old | |
336 | .I stx_mode | |
337 | together with the new | |
338 | .IR stx_uid , | |
339 | or the old | |
340 | .I stx_uid | |
341 | together with the new | |
342 | .IR stx_mode . | |
343 | .PP | |
77a09ad7 MK |
344 | Apart from |
345 | .I stx_mask | |
346 | (which is described above), the fields in the | |
9905e59b DH |
347 | .I statx |
348 | structure are: | |
349 | .TP | |
13470fd3 MK |
350 | .I stx_blksize |
351 | The "preferred" block size for efficient filesystem I/O. | |
352 | (Writing to a file in | |
353 | smaller chunks may cause an inefficient read-modify-rewrite.) | |
354 | .TP | |
355 | .I stx_attributes | |
356 | Further status information about the file (see below for more information). | |
357 | .TP | |
358 | .I stx_nlink | |
359 | The number of hard links on a file. | |
360 | .TP | |
361 | .I stx_uid | |
362 | This field contains the user ID of the owner of the file. | |
363 | .TP | |
364 | .I stx_gid | |
365 | This field contains the ID of the group owner of the file. | |
aabbefb4 | 366 | .TP |
9905e59b | 367 | .I stx_mode |
14b5d02a | 368 | The file type and mode. |
19cda35d MK |
369 | See |
370 | .BR inode (7) | |
371 | for details. | |
9905e59b | 372 | .TP |
fc31d730 MK |
373 | .I stx_ino |
374 | The inode number of the file. | |
375 | .TP | |
9905e59b DH |
376 | .I stx_size |
377 | The size of the file (if it is a regular file or a symbolic link) in bytes. | |
ffe297ee MK |
378 | The size of a symbolic link is the length of the pathname it contains, |
379 | without a terminating null byte. | |
9905e59b DH |
380 | .TP |
381 | .I stx_blocks | |
382 | The number of blocks allocated to the file on the medium, in 512-byte units. | |
383 | (This may be smaller than | |
384 | .IR stx_size /512 | |
385 | when the file has holes.) | |
386 | .TP | |
13470fd3 MK |
387 | .I stx_attributes_mask |
388 | A mask indicating which bits in | |
1ae6b2c7 | 389 | .I stx_attributes |
13470fd3 | 390 | are supported by the VFS and the filesystem. |
9905e59b DH |
391 | .TP |
392 | .I stx_atime | |
393 | The file's last access timestamp. | |
9905e59b DH |
394 | .TP |
395 | .I stx_btime | |
14b5d02a | 396 | The file's creation timestamp. |
9905e59b DH |
397 | .TP |
398 | .I stx_ctime | |
14b5d02a | 399 | The file's last status change timestamp. |
9905e59b DH |
400 | .TP |
401 | .I stx_mtime | |
14b5d02a | 402 | The file's last modification timestamp. |
13470fd3 MK |
403 | .TP |
404 | .IR stx_dev_major " and " stx_dev_minor | |
405 | The device on which this file (inode) resides. | |
406 | .TP | |
407 | .IR stx_rdev_major " and " stx_rdev_minor | |
408 | The device that this file (inode) represents if the file is of block or | |
409 | character device type. | |
728009a4 N |
410 | .TP |
411 | .I stx_mnt_id | |
412 | .\" commit fa2fcf4f1df1559a0a4ee0f46915b496cc2ebf60 | |
053132a8 MK |
413 | The mount ID of the mount containing the file. |
414 | This is the same number reported by | |
728009a4 N |
415 | .BR name_to_handle_at (2) |
416 | and corresponds to the number in the first field in one of the records in | |
417 | .IR /proc/self/mountinfo . | |
ed1cff15 EB |
418 | .TP |
419 | .I stx_dio_mem_align | |
420 | The alignment (in bytes) required for user memory buffers for direct I/O | |
421 | .RB ( O_DIRECT ) | |
422 | on this file, | |
423 | or 0 if direct I/O is not supported on this file. | |
424 | .IP | |
425 | .B STATX_DIOALIGN | |
426 | .RI ( stx_dio_mem_align | |
427 | and | |
428 | .IR stx_dio_offset_align ) | |
429 | is supported on block devices since Linux 6.1. | |
430 | The support on regular files varies by filesystem; | |
431 | it is supported by ext4, f2fs, and xfs since Linux 6.1. | |
432 | .TP | |
433 | .I stx_dio_offset_align | |
434 | The alignment (in bytes) required for file offsets and I/O segment lengths | |
435 | for direct I/O | |
436 | .RB ( O_DIRECT ) | |
437 | on this file, | |
438 | or 0 if direct I/O is not supported on this file. | |
439 | This will only be nonzero if | |
440 | .I stx_dio_mem_align | |
441 | is nonzero, and vice versa. | |
9905e59b | 442 | .PP |
19cda35d MK |
443 | For further information on the above fields, see |
444 | .BR inode (7). | |
14b5d02a | 445 | .\" |
9905e59b | 446 | .SS File attributes |
9905e59b DH |
447 | The |
448 | .I stx_attributes | |
c8701baf | 449 | field contains a set of ORed flags that indicate additional attributes |
aabbefb4 MK |
450 | of the file. |
451 | Note that any attribute that is not indicated as supported by | |
452 | .I stx_attributes_mask | |
453 | has no usable value here. | |
454 | The bits in | |
455 | .I stx_attributes_mask | |
456 | correspond bit-by-bit to | |
457 | .IR stx_attributes . | |
efeece04 | 458 | .PP |
aabbefb4 | 459 | The flags are as follows: |
9905e59b | 460 | .TP |
77a09ad7 | 461 | .B STATX_ATTR_COMPRESSED |
56a05af6 MK |
462 | The file is compressed by the filesystem and may take extra resources |
463 | to access. | |
9905e59b | 464 | .TP |
77a09ad7 | 465 | .B STATX_ATTR_IMMUTABLE |
ffe297ee MK |
466 | The file cannot be modified: it cannot be deleted or renamed, |
467 | no hard links can be created to this file and no data can be written to it. | |
709f7bb6 MK |
468 | See |
469 | .BR chattr (1). | |
9905e59b | 470 | .TP |
77a09ad7 | 471 | .B STATX_ATTR_APPEND |
14b5d02a MK |
472 | The file can only be opened in append mode for writing. |
473 | Random access writing | |
474 | is not permitted. | |
709f7bb6 MK |
475 | See |
476 | .BR chattr (1). | |
9905e59b | 477 | .TP |
77a09ad7 | 478 | .B STATX_ATTR_NODUMP |
709f7bb6 MK |
479 | File is not a candidate for backup when a backup program such as |
480 | .BR dump (8) | |
481 | is run. | |
482 | See | |
483 | .BR chattr (1). | |
9905e59b | 484 | .TP |
77a09ad7 | 485 | .B STATX_ATTR_ENCRYPTED |
9905e59b | 486 | A key is required for the file to be encrypted by the filesystem. |
ba2a5200 | 487 | .TP |
c436f71f MK |
488 | .BR STATX_ATTR_VERITY " (since Linux 5.5)" |
489 | .\" commit 3ad2522c64cff1f5aebb987b00683268f0cc7c29 | |
490 | The file has fs-verity enabled. | |
491 | It cannot be written to, and all reads from it will be verified | |
492 | against a cryptographic hash that covers the | |
493 | entire file (e.g., via a Merkle tree). | |
38ad6a88 | 494 | .TP |
2e335632 | 495 | .BR STATX_ATTR_DAX " (since Linux 5.8)" |
c9e6c5ab MK |
496 | The file is in the DAX (cpu direct access) state. |
497 | DAX state attempts to | |
38ad6a88 IW |
498 | minimize software cache effects for both I/O and memory mappings of this file. |
499 | It requires a file system which has been configured to support DAX. | |
2e335632 | 500 | .IP |
c9e6c5ab MK |
501 | DAX generally assumes all accesses are via CPU load / store instructions |
502 | which can minimize overhead for small accesses, | |
503 | but may adversely affect CPU utilization for large transfers. | |
2e335632 | 504 | .IP |
38ad6a88 | 505 | File I/O is done directly to/from user-space buffers and memory mapped I/O may |
c9e6c5ab | 506 | be performed with direct memory mappings that bypass the kernel page cache. |
2e335632 | 507 | .IP |
38ad6a88 | 508 | While the DAX property tends to result in data being transferred synchronously, |
c9e6c5ab MK |
509 | it does not give the same guarantees as the |
510 | .B O_SYNC | |
511 | flag (see | |
512 | .BR open (2)), | |
513 | where data and the necessary metadata are transferred together. | |
2e335632 | 514 | .IP |
c9e6c5ab MK |
515 | A DAX file may support being mapped with the |
516 | .B MAP_SYNC | |
517 | flag, which enables a | |
38ad6a88 IW |
518 | program to use CPU cache flush instructions to persist CPU store operations |
519 | without an explicit | |
c9e6c5ab | 520 | .BR fsync (2). |
38ad6a88 | 521 | See |
c9e6c5ab | 522 | .BR mmap (2) |
38ad6a88 | 523 | for more information. |
9905e59b DH |
524 | .SH RETURN VALUE |
525 | On success, zero is returned. | |
526 | On error, \-1 is returned, and | |
527 | .I errno | |
f6a4078b | 528 | is set to indicate the error. |
9905e59b DH |
529 | .SH ERRORS |
530 | .TP | |
9905e59b DH |
531 | .B EACCES |
532 | Search permission is denied for one of the directories | |
533 | in the path prefix of | |
534 | .IR pathname . | |
535 | (See also | |
536 | .BR path_resolution (7).) | |
537 | .TP | |
538 | .B EBADF | |
9f4e736a MK |
539 | .I pathname |
540 | is relative but | |
9905e59b | 541 | .I dirfd |
9f4e736a MK |
542 | is neither |
543 | .B AT_FDCWD | |
544 | nor a valid file descriptor. | |
9905e59b DH |
545 | .TP |
546 | .B EFAULT | |
09ff9f4a MK |
547 | .I pathname |
548 | or | |
15d1f5ac | 549 | .I statxbuf |
09ff9f4a MK |
550 | is NULL or points to a location outside the process's |
551 | accessible address space. | |
9905e59b | 552 | .TP |
1b206bd8 MK |
553 | .B EINVAL |
554 | Invalid flag specified in | |
555 | .IR flags . | |
556 | .TP | |
aabbefb4 MK |
557 | .B EINVAL |
558 | Reserved flag specified in | |
559 | .IR mask . | |
c031ffcc MK |
560 | (Currently, there is one such flag, designated by the constant |
561 | .BR STATX__RESERVED , | |
562 | with the value 0x80000000U.) | |
aabbefb4 | 563 | .TP |
9905e59b | 564 | .B ELOOP |
835f4293 | 565 | Too many symbolic links encountered while traversing the pathname. |
9905e59b DH |
566 | .TP |
567 | .B ENAMETOOLONG | |
568 | .I pathname | |
569 | is too long. | |
570 | .TP | |
571 | .B ENOENT | |
572 | A component of | |
573 | .I pathname | |
574 | does not exist, or | |
575 | .I pathname | |
c8701baf MK |
576 | is an empty string and |
577 | .B AT_EMPTY_PATH | |
578 | was not specified in | |
579 | .IR flags . | |
9905e59b DH |
580 | .TP |
581 | .B ENOMEM | |
582 | Out of memory (i.e., kernel memory). | |
583 | .TP | |
584 | .B ENOTDIR | |
585 | A component of the path prefix of | |
586 | .I pathname | |
587 | is not a directory or | |
588 | .I pathname | |
589 | is relative and | |
590 | .I dirfd | |
591 | is a file descriptor referring to a file other than a directory. | |
592 | .SH VERSIONS | |
593 | .BR statx () | |
b324e17d | 594 | was added in Linux 4.11; library support was added in glibc 2.28. |
3113c7f3 | 595 | .SH STANDARDS |
7a192d0d | 596 | .BR statx () |
56a05af6 | 597 | is Linux-specific. |
9905e59b DH |
598 | .SH SEE ALSO |
599 | .BR ls (1), | |
600 | .BR stat (1), | |
601 | .BR access (2), | |
602 | .BR chmod (2), | |
603 | .BR chown (2), | |
728009a4 | 604 | .BR name_to_handle_at (2), |
9905e59b | 605 | .BR readlink (2), |
6edadda6 | 606 | .BR stat (2), |
9905e59b | 607 | .BR utime (2), |
728009a4 | 608 | .BR proc (5), |
9905e59b | 609 | .BR capabilities (7), |
3b363b62 | 610 | .BR inode (7), |
9905e59b | 611 | .BR symlink (7) |