Debian Codegraph @

upstream/debian-unstable/man2/statx.2

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