Debian Codegraph @

upstream/fedora-44/man2/statx.2

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