| 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) |