2 .\" Copyright (c) 2017 David Howells <dhowells@redhat.com>
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>
9 .\" %%%LICENSE_START(VERBATIM)
10 .\" Permission is granted to make and distribute verbatim copies of this
11 .\" manual provided the copyright notice and this permission notice are
12 .\" preserved on all copies.
14 .\" Permission is granted to copy and distribute modified versions of this
15 .\" manual under the conditions for verbatim copying, provided that the
16 .\" entire resulting derived work is distributed under the terms of a
17 .\" permission notice identical to this one.
19 .\" Since the Linux kernel and libraries are constantly changing, this
20 .\" manual page may be incorrect or out-of-date. The author(s) assume no
21 .\" responsibility for errors or omissions, or for damages resulting from
22 .\" the use of the information contained herein. The author(s) may not
23 .\" have taken the same level of care in the production of this manual,
24 .\" which is licensed free of charge, as they might when working
27 .\" Formatted or processed versions of this manual, if unaccompanied by
28 .\" the source, must acknowledge the copyright and authors of this work.
31 .TH STATX 2 2017-05-03 "Linux" "Linux Programmer's Manual"
33 statx \- get file status (extended)
36 .B #include <sys/types.h>
37 .B #include <sys/stat.h>
38 .B #include <unistd.h>
39 .BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
41 .BI "int statx(int " dirfd ", const char *" pathname ", int " flags ","
42 .BI " unsigned int " mask ", struct statx *" statxbuf );
46 There is no glibc wrapper for
51 This function returns information about a file, storing it in the buffer
54 The returned buffer is a structure of the following type:
59 __u32 stx_mask; /* Mask of bits indicating
61 __u32 stx_blksize; /* Block size for filesystem I/O */
62 __u64 stx_attributes; /* Extra file attribute indicators */
63 __u32 stx_nlink; /* Number of hard links */
64 __u32 stx_uid; /* User ID of owner */
65 __u32 stx_gid; /* Group ID of owner */
66 __u16 stx_mode; /* File type and mode */
67 __u64 stx_ino; /* Inode number */
68 __u64 stx_size; /* Total size in bytes */
69 __u64 stx_blocks; /* Number of 512B blocks allocated */
70 __u64 stx_attributes_mask;
71 /* Mask to show what's supported
74 /* The following fields are file timestamps */
75 struct statx_timestamp stx_atime; /* Last access */
76 struct statx_timestamp stx_btime; /* Creation */
77 struct statx_timestamp stx_ctime; /* Last status change */
78 struct statx_timestamp stx_mtime; /* Last modification */
80 /* If this file represents a device, then the next two
81 fields contain the ID of the device */
82 __u32 stx_rdev_major; /* Major ID */
83 __u32 stx_rdev_minor; /* Minor ID */
85 /* The next two fields contain the ID of the device
86 containing the filesystem where the file resides */
87 __u32 stx_dev_major; /* Major ID */
88 __u32 stx_dev_minor; /* Minor ID */
93 The file timestamps are structures of the following type:
97 struct statx_timestamp {
98 __s64 tv_sec; /* Seconds since the Epoch (UNIX time) */
99 __u32 tv_nsec; /* Nanoseconds since tv_sec */
104 (Note that reserved space and padding is omitted.)
106 Invoking \fBstatx\fR():
108 To access a file's status, no permissions are required on the file itself,
112 execute (search) permission is required on all of the directories in
114 that lead to the file.
122 to identify the target file in one of the following ways:
128 then it is an absolute pathname that identifies the target file.
136 is a string that begins with a character other than a slash and
142 is a relative pathname that is interpreted relative to the process's
143 current working directory.
145 A directory-relative pathname
148 is a string that begins with a character other than a slash and
150 is a file descriptor that refers to a directory, then
152 is a relative pathname that is interpreted relative to the directory
159 is an empty string and the
164 then the target file is the one referred to by the file descriptor
168 can be used to influence a pathname-based lookup.
171 is constructed by ORing together zero or more of the following constants:
174 .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d
177 is an empty string, operate on the file referred to by
179 (which may have been obtained using the
185 can refer to any type of file, not just a directory.
191 the call operates on the current working directory.
193 This flag is Linux-specific; define
195 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
196 to obtain its definition.
199 Don't automount the terminal ("basename") component of
201 if it is a directory that is an automount point.
202 This allows the caller to gather attributes of an automount point
203 (rather than the location it would mount).
204 This flag can be used in tools that scan directories
205 to prevent mass-automounting of a directory of automount points.
208 flag has no effect if the mount point has already been mounted over.
209 This flag is Linux-specific; define
211 .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed
212 to obtain its definition.
214 .B AT_SYMLINK_NOFOLLOW
217 is a symbolic link, do not dereference it:
218 instead return information about the link itself, like
222 can also be used to control what sort of synchronization the kernel will do
223 when querying a file on a remote filesystem.
224 This is done by ORing in one of the following values:
226 .B AT_STATX_SYNC_AS_STAT
230 This is the default and is very much filesystem-specific.
232 .B AT_STATX_FORCE_SYNC
233 Force the attributes to be synchronized with the server.
234 This may require that
235 a network filesystem perform a data writeback to get the timestamps correct.
237 .B AT_STATX_DONT_SYNC
238 Don't synchronize anything, but rather just take whatever
239 the system has cached if possible.
240 This may mean that the information returned is approximate, but,
241 on a network filesystem, it may not involve a round trip to the server - even
248 is used to tell the kernel which fields the caller is interested in.
250 is an ORed combination of the following constants:
255 STATX_TYPE Want stx_mode & S_IFMT
256 STATX_MODE Want stx_mode & ~S_IFMT
257 STATX_NLINK Want stx_nlink
258 STATX_UID Want stx_uid
259 STATX_GID Want stx_gid
260 STATX_ATIME Want stx_atime
261 STATX_MTIME Want stx_mtime
262 STATX_CTIME Want stx_ctime
263 STATX_INO Want stx_ino
264 STATX_SIZE Want stx_size
265 STATX_BLOCKS Want stx_blocks
266 STATX_BASIC_STATS [All of the above]
267 STATX_BTIME Want stx_btime
268 STATX_ALL [All currently available fields]
272 Note that the kernel does
276 other than the above.
277 Instead, it simply informs the caller which values are supported
278 by this kernel and filesystem via the
288 as one or more bits may, in the future, be used to specify an
289 extension to the buffer.
291 The returned information
293 The status information for the target file is returned in the
295 structure pointed to by
299 which indicates what other information has been returned.
301 has the same format as the
303 argument and bits are set in it to indicate
304 which fields have been filled in.
306 It should be noted that the kernel may return fields that weren't
307 requested and may fail to return fields that were requested,
308 depending on what the backing filesystem supports.
309 (Fields that are given values despite being unrequested can just be ignored.)
315 If a filesystem does not support a field or if it has
316 an unrepresentable value (for instance, a file with an exotic type),
317 then the mask bit corresponding to that field will be cleared in
319 even if the user asked for it and a dummy value will be filled in for
320 compatibility purposes if one is available (e.g., a dummy UID and GID may be
321 specified to mount under some circumstances).
323 A filesystem may also fill in fields that the caller didn't ask for if it has
324 values for them available and the information is available at no extra cost.
325 If this happens, the corresponding bits will be set in
328 .\" Background: inode attributes are modified with i_mutex held, but
329 .\" read by stat() without taking the mutex.
331 for performance and simplicity reasons, different fields in the
333 structure may contain state information from different moments
334 during the execution of the system call.
339 is changed by another process by calling
346 together with the new
350 together with the new
355 (which is described above), the fields in the
360 The "preferred" block size for efficient filesystem I/O.
361 (Writing to a file in
362 smaller chunks may cause an inefficient read-modify-rewrite.)
365 Further status information about the file (see below for more information).
368 The number of hard links on a file.
371 This field contains the user ID of the owner of the file.
374 This field contains the ID of the group owner of the file.
377 The file type and mode.
383 The inode number of the file.
386 The size of the file (if it is a regular file or a symbolic link) in bytes.
387 The size of a symbolic link is the length of the pathname it contains,
388 without a terminating null byte.
391 The number of blocks allocated to the file on the medium, in 512-byte units.
392 (This may be smaller than
394 when the file has holes.)
396 .I stx_attributes_mask
397 A mask indicating which bits in
399 are supported by the VFS and the filesystem.
402 The file's last access timestamp.
405 The file's creation timestamp.
408 The file's last status change timestamp.
411 The file's last modification timestamp.
413 .IR stx_dev_major " and " stx_dev_minor
414 The device on which this file (inode) resides.
416 .IR stx_rdev_major " and " stx_rdev_minor
417 The device that this file (inode) represents if the file is of block or
418 character device type.
420 For further information on the above fields, see
427 field contains a set of ORed flags that indicate additional attributes
429 Note that any attribute that is not indicated as supported by
430 .I stx_attributes_mask
431 has no usable value here.
433 .I stx_attributes_mask
434 correspond bit-by-bit to
437 The flags are as follows:
439 .B STATX_ATTR_COMPRESSED
440 The file is compressed by the filesystem and may take extra resources
443 .B STATX_ATTR_IMMUTABLE
444 The file cannot be modified: it cannot be deleted or renamed,
445 no hard links can be created to this file and no data can be written to it.
450 The file can only be opened in append mode for writing.
451 Random access writing
457 File is not a candidate for backup when a backup program such as
463 .B STATX_ATTR_ENCRYPTED
464 A key is required for the file to be encrypted by the filesystem.
466 On success, zero is returned.
467 On error, \-1 is returned, and
469 is set appropriately.
473 Search permission is denied for one of the directories
474 in the path prefix of
477 .BR path_resolution (7).)
481 is not a valid open file descriptor.
487 is NULL or points to a location outside the process's
488 accessible address space.
491 Invalid flag specified in
495 Reserved flag specified in
499 Too many symbolic links encountered while traversing the pathname.
510 is an empty string and
516 Out of memory (i.e., kernel memory).
519 A component of the path prefix of
521 is not a directory or
525 is a file descriptor referring to a file other than a directory.
528 was added to Linux in kernel 4.11.
533 Glibc does not (yet) provide a wrapper for the
535 system call; call it using
546 .BR capabilities (7),