1 .\" Copyright (c) 2017 David Howells <dhowells@redhat.com>
3 .\" Derived from the stat.2 manual page:
4 .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992
5 .\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95
6 .\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com>
8 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
10 .TH STATX 2 2021-08-27 "Linux man-pages (unreleased)"
12 statx \- get file status (extended)
15 .RI ( libc ", " \-lc )
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>
22 .BI "int statx(int " dirfd ", const char *restrict " pathname ", int " flags ,
23 .BI " unsigned int " mask ", struct statx *restrict " statxbuf );
26 This function returns information about a file, storing it in the buffer
29 The returned buffer is a structure of the following type:
34 __u32 stx_mask; /* Mask of bits indicating
36 __u32 stx_blksize; /* Block size for filesystem I/O */
37 __u64 stx_attributes; /* Extra file attribute indicators */
38 __u32 stx_nlink; /* Number of hard links */
39 __u32 stx_uid; /* User ID of owner */
40 __u32 stx_gid; /* Group ID of owner */
41 __u16 stx_mode; /* File type and mode */
42 __u64 stx_ino; /* Inode number */
43 __u64 stx_size; /* Total size in bytes */
44 __u64 stx_blocks; /* Number of 512B blocks allocated */
45 __u64 stx_attributes_mask;
46 /* Mask to show what\(aqs supported
49 /* The following fields are file timestamps */
50 struct statx_timestamp stx_atime; /* Last access */
51 struct statx_timestamp stx_btime; /* Creation */
52 struct statx_timestamp stx_ctime; /* Last status change */
53 struct statx_timestamp stx_mtime; /* Last modification */
55 /* If this file represents a device, then the next two
56 fields contain the ID of the device */
57 __u32 stx_rdev_major; /* Major ID */
58 __u32 stx_rdev_minor; /* Minor ID */
60 /* The next two fields contain the ID of the device
61 containing the filesystem where the file resides */
62 __u32 stx_dev_major; /* Major ID */
63 __u32 stx_dev_minor; /* Minor ID */
64 __u64 stx_mnt_id; /* Mount ID */
69 The file timestamps are structures of the following type:
73 struct statx_timestamp {
74 __s64 tv_sec; /* Seconds since the Epoch (UNIX time) */
75 __u32 tv_nsec; /* Nanoseconds since tv_sec */
80 (Note that reserved space and padding is omitted.)
82 Invoking \fBstatx\fR():
83 To access a file's status, no permissions are required on the file itself,
87 execute (search) permission is required on all of the directories in
89 that lead to the file.
97 to identify the target file in one of the following ways:
103 then it is an absolute pathname that identifies the target file.
111 is a string that begins with a character other than a slash and
117 is a relative pathname that is interpreted relative to the process's
118 current working directory.
120 A directory-relative pathname
123 is a string that begins with a character other than a slash and
125 is a file descriptor that refers to a directory, then
127 is a relative pathname that is interpreted relative to the directory
132 for an explanation of why this is useful.)
137 is an empty string and the
142 then the target file is the one referred to by the file descriptor
146 can be used to influence a pathname-based lookup.
149 is constructed by ORing together zero or more of the following constants:
152 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
155 is an empty string, operate on the file referred to by
157 (which may have been obtained using the
163 can refer to any type of file, not just a directory.
169 the call operates on the current working directory.
172 Don't automount the terminal ("basename") component of
174 if it is a directory that is an automount point.
175 This allows the caller to gather attributes of an automount point
176 (rather than the location it would mount).
177 This flag has no effect if the mount point has already been mounted over.
181 flag can be used in tools that scan directories
182 to prevent mass-automounting of a directory of automount points.
193 .B AT_SYMLINK_NOFOLLOW
196 is a symbolic link, do not dereference it:
197 instead return information about the link itself, like
201 can also be used to control what sort of synchronization the kernel will do
202 when querying a file on a remote filesystem.
203 This is done by ORing in one of the following values:
205 .B AT_STATX_SYNC_AS_STAT
209 This is the default and is very much filesystem-specific.
211 .B AT_STATX_FORCE_SYNC
212 Force the attributes to be synchronized with the server.
213 This may require that
214 a network filesystem perform a data writeback to get the timestamps correct.
216 .B AT_STATX_DONT_SYNC
217 Don't synchronize anything, but rather just take whatever
218 the system has cached if possible.
219 This may mean that the information returned is approximate, but,
220 on a network filesystem, it may not involve a round trip to the server - even
227 is used to tell the kernel which fields the caller is interested in.
229 is an ORed combination of the following constants:
234 STATX_TYPE Want stx_mode & S_IFMT
235 STATX_MODE Want stx_mode & \(tiS_IFMT
236 STATX_NLINK Want stx_nlink
237 STATX_UID Want stx_uid
238 STATX_GID Want stx_gid
239 STATX_ATIME Want stx_atime
240 STATX_MTIME Want stx_mtime
241 STATX_CTIME Want stx_ctime
242 STATX_INO Want stx_ino
243 STATX_SIZE Want stx_size
244 STATX_BLOCKS Want stx_blocks
245 STATX_BASIC_STATS [All of the above]
246 STATX_BTIME Want stx_btime
247 STATX_ALL The same as STATX_BASIC_STATS | STATX_BTIME.
248 It is deprecated and should not be used.
249 STATX_MNT_ID Want stx_mnt_id (since Linux 5.8)
253 Note that, in general, the kernel does
257 other than the above.
258 (For an exception, see
261 Instead, it simply informs the caller which values are supported
262 by this kernel and filesystem via the
272 as one or more bits may, in the future, be used to specify an
273 extension to the buffer.
275 The returned information
276 The status information for the target file is returned in the
278 structure pointed to by
282 which indicates what other information has been returned.
284 has the same format as the
286 argument and bits are set in it to indicate
287 which fields have been filled in.
289 It should be noted that the kernel may return fields that weren't
290 requested and may fail to return fields that were requested,
291 depending on what the backing filesystem supports.
292 (Fields that are given values despite being unrequested can just be ignored.)
298 If a filesystem does not support a field or if it has
299 an unrepresentable value (for instance, a file with an exotic type),
300 then the mask bit corresponding to that field will be cleared in
302 even if the user asked for it and a dummy value will be filled in for
303 compatibility purposes if one is available (e.g., a dummy UID and GID may be
304 specified to mount under some circumstances).
306 A filesystem may also fill in fields that the caller didn't ask for if it has
307 values for them available and the information is available at no extra cost.
308 If this happens, the corresponding bits will be set in
311 .\" Background: inode attributes are modified with i_mutex held, but
312 .\" read by stat() without taking the mutex.
314 for performance and simplicity reasons, different fields in the
316 structure may contain state information from different moments
317 during the execution of the system call.
322 is changed by another process by calling
329 together with the new
333 together with the new
338 (which is described above), the fields in the
343 The "preferred" block size for efficient filesystem I/O.
344 (Writing to a file in
345 smaller chunks may cause an inefficient read-modify-rewrite.)
348 Further status information about the file (see below for more information).
351 The number of hard links on a file.
354 This field contains the user ID of the owner of the file.
357 This field contains the ID of the group owner of the file.
360 The file type and mode.
366 The inode number of the file.
369 The size of the file (if it is a regular file or a symbolic link) in bytes.
370 The size of a symbolic link is the length of the pathname it contains,
371 without a terminating null byte.
374 The number of blocks allocated to the file on the medium, in 512-byte units.
375 (This may be smaller than
377 when the file has holes.)
379 .I stx_attributes_mask
380 A mask indicating which bits in
382 are supported by the VFS and the filesystem.
385 The file's last access timestamp.
388 The file's creation timestamp.
391 The file's last status change timestamp.
394 The file's last modification timestamp.
396 .IR stx_dev_major " and " stx_dev_minor
397 The device on which this file (inode) resides.
399 .IR stx_rdev_major " and " stx_rdev_minor
400 The device that this file (inode) represents if the file is of block or
401 character device type.
404 .\" commit fa2fcf4f1df1559a0a4ee0f46915b496cc2ebf60
405 The mount ID of the mount containing the file.
406 This is the same number reported by
407 .BR name_to_handle_at (2)
408 and corresponds to the number in the first field in one of the records in
409 .IR /proc/self/mountinfo .
411 For further information on the above fields, see
417 field contains a set of ORed flags that indicate additional attributes
419 Note that any attribute that is not indicated as supported by
420 .I stx_attributes_mask
421 has no usable value here.
423 .I stx_attributes_mask
424 correspond bit-by-bit to
427 The flags are as follows:
429 .B STATX_ATTR_COMPRESSED
430 The file is compressed by the filesystem and may take extra resources
433 .B STATX_ATTR_IMMUTABLE
434 The file cannot be modified: it cannot be deleted or renamed,
435 no hard links can be created to this file and no data can be written to it.
440 The file can only be opened in append mode for writing.
441 Random access writing
447 File is not a candidate for backup when a backup program such as
453 .B STATX_ATTR_ENCRYPTED
454 A key is required for the file to be encrypted by the filesystem.
456 .BR STATX_ATTR_VERITY " (since Linux 5.5)"
457 .\" commit 3ad2522c64cff1f5aebb987b00683268f0cc7c29
458 The file has fs-verity enabled.
459 It cannot be written to, and all reads from it will be verified
460 against a cryptographic hash that covers the
461 entire file (e.g., via a Merkle tree).
463 .BR STATX_ATTR_DAX " (since Linux 5.8)"
464 The file is in the DAX (cpu direct access) state.
465 DAX state attempts to
466 minimize software cache effects for both I/O and memory mappings of this file.
467 It requires a file system which has been configured to support DAX.
469 DAX generally assumes all accesses are via CPU load / store instructions
470 which can minimize overhead for small accesses,
471 but may adversely affect CPU utilization for large transfers.
473 File I/O is done directly to/from user-space buffers and memory mapped I/O may
474 be performed with direct memory mappings that bypass the kernel page cache.
476 While the DAX property tends to result in data being transferred synchronously,
477 it does not give the same guarantees as the
481 where data and the necessary metadata are transferred together.
483 A DAX file may support being mapped with the
485 flag, which enables a
486 program to use CPU cache flush instructions to persist CPU store operations
491 for more information.
493 On success, zero is returned.
494 On error, \-1 is returned, and
496 is set to indicate the error.
500 Search permission is denied for one of the directories
501 in the path prefix of
504 .BR path_resolution (7).)
512 nor a valid file descriptor.
518 is NULL or points to a location outside the process's
519 accessible address space.
522 Invalid flag specified in
526 Reserved flag specified in
528 (Currently, there is one such flag, designated by the constant
529 .BR STATX__RESERVED ,
530 with the value 0x80000000U.)
533 Too many symbolic links encountered while traversing the pathname.
544 is an empty string and
550 Out of memory (i.e., kernel memory).
553 A component of the path prefix of
555 is not a directory or
559 is a file descriptor referring to a file other than a directory.
562 was added to Linux in kernel 4.11; library support was added in glibc 2.28.
572 .BR name_to_handle_at (2),
577 .BR capabilities (7),