| .\" Copyright (c) 2017 David Howells <dhowells@redhat.com> |
| .\" |
| .\" Derived from the stat.2 manual page: |
| .\" Copyright (c) 1992 Drew Eckhardt (drew@cs.colorado.edu), March 28, 1992 |
| .\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@ifi.uio.no), 1/1/95 |
| .\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@gmail.com> |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" Permission is granted to make and distribute verbatim copies of this |
| .\" manual provided the copyright notice and this permission notice are |
| .\" preserved on all copies. |
| .\" |
| .\" Permission is granted to copy and distribute modified versions of this |
| .\" manual under the conditions for verbatim copying, provided that the |
| .\" entire resulting derived work is distributed under the terms of a |
| .\" permission notice identical to this one. |
| .\" |
| .\" Since the Linux kernel and libraries are constantly changing, this |
| .\" manual page may be incorrect or out-of-date. The author(s) assume no |
| .\" responsibility for errors or omissions, or for damages resulting from |
| .\" the use of the information contained herein. The author(s) may not |
| .\" have taken the same level of care in the production of this manual, |
| .\" which is licensed free of charge, as they might when working |
| .\" professionally. |
| .\" |
| .\" Formatted or processed versions of this manual, if unaccompanied by |
| .\" the source, must acknowledge the copyright and authors of this work. |
| .\" %%%LICENSE_END |
| .\" |
| .TH STATX 2 2020-04-11 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| statx \- get file status (extended) |
| .SH SYNOPSIS |
| .nf |
| .B #include <sys/types.h> |
| .B #include <sys/stat.h> |
| .B #include <unistd.h> |
| .BR "#include <fcntl.h> " "/* Definition of AT_* constants */" |
| .PP |
| .BI "int statx(int " dirfd ", const char *" pathname ", int " flags "," |
| .BI " unsigned int " mask ", struct statx *" statxbuf ); |
| .fi |
| .SH DESCRIPTION |
| This function returns information about a file, storing it in the buffer |
| pointed to by |
| .IR statxbuf . |
| The returned buffer is a structure of the following type: |
| .PP |
| .in +4n |
| .EX |
| struct statx { |
| __u32 stx_mask; /* Mask of bits indicating |
| filled fields */ |
| __u32 stx_blksize; /* Block size for filesystem I/O */ |
| __u64 stx_attributes; /* Extra file attribute indicators */ |
| __u32 stx_nlink; /* Number of hard links */ |
| __u32 stx_uid; /* User ID of owner */ |
| __u32 stx_gid; /* Group ID of owner */ |
| __u16 stx_mode; /* File type and mode */ |
| __u64 stx_ino; /* Inode number */ |
| __u64 stx_size; /* Total size in bytes */ |
| __u64 stx_blocks; /* Number of 512B blocks allocated */ |
| __u64 stx_attributes_mask; |
| /* Mask to show what's supported |
| in stx_attributes */ |
| |
| /* The following fields are file timestamps */ |
| struct statx_timestamp stx_atime; /* Last access */ |
| struct statx_timestamp stx_btime; /* Creation */ |
| struct statx_timestamp stx_ctime; /* Last status change */ |
| struct statx_timestamp stx_mtime; /* Last modification */ |
| |
| /* If this file represents a device, then the next two |
| fields contain the ID of the device */ |
| __u32 stx_rdev_major; /* Major ID */ |
| __u32 stx_rdev_minor; /* Minor ID */ |
| |
| /* The next two fields contain the ID of the device |
| containing the filesystem where the file resides */ |
| __u32 stx_dev_major; /* Major ID */ |
| __u32 stx_dev_minor; /* Minor ID */ |
| }; |
| .EE |
| .in |
| .PP |
| The file timestamps are structures of the following type: |
| .PP |
| .in +4n |
| .EX |
| struct statx_timestamp { |
| __s64 tv_sec; /* Seconds since the Epoch (UNIX time) */ |
| __u32 tv_nsec; /* Nanoseconds since tv_sec */ |
| }; |
| .EE |
| .in |
| .PP |
| (Note that reserved space and padding is omitted.) |
| .SS |
| Invoking \fBstatx\fR(): |
| To access a file's status, no permissions are required on the file itself, |
| but in the case of |
| .BR statx () |
| with a pathname, |
| execute (search) permission is required on all of the directories in |
| .I pathname |
| that lead to the file. |
| .PP |
| .BR statx () |
| uses |
| .IR pathname , |
| .IR dirfd , |
| and |
| .IR flags |
| to identify the target file in one of the following ways: |
| .TP |
| An absolute pathname |
| If |
| .I pathname |
| begins with a slash, |
| then it is an absolute pathname that identifies the target file. |
| In this case, |
| .I dirfd |
| is ignored. |
| .TP |
| A relative pathname |
| If |
| .I pathname |
| is a string that begins with a character other than a slash and |
| .IR dirfd |
| is |
| .BR AT_FDCWD , |
| then |
| .I pathname |
| is a relative pathname that is interpreted relative to the process's |
| current working directory. |
| .TP |
| A directory-relative pathname |
| If |
| .I pathname |
| is a string that begins with a character other than a slash and |
| .I dirfd |
| is a file descriptor that refers to a directory, then |
| .I pathname |
| is a relative pathname that is interpreted relative to the directory |
| referred to by |
| .IR dirfd . |
| .TP |
| By file descriptor |
| If |
| .IR pathname |
| is an empty string and the |
| .B AT_EMPTY_PATH |
| flag is specified in |
| .IR flags |
| (see below), |
| then the target file is the one referred to by the file descriptor |
| .IR dirfd . |
| .PP |
| .I flags |
| can be used to influence a pathname-based lookup. |
| A value for |
| .I flags |
| is constructed by ORing together zero or more of the following constants: |
| .TP |
| .BR AT_EMPTY_PATH |
| .\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d |
| If |
| .I pathname |
| is an empty string, operate on the file referred to by |
| .IR dirfd |
| (which may have been obtained using the |
| .BR open (2) |
| .B O_PATH |
| flag). |
| In this case, |
| .I dirfd |
| can refer to any type of file, not just a directory. |
| .IP |
| If |
| .I dirfd |
| is |
| .BR AT_FDCWD , |
| the call operates on the current working directory. |
| .IP |
| This flag is Linux-specific; define |
| .B _GNU_SOURCE |
| .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed |
| to obtain its definition. |
| .TP |
| .BR AT_NO_AUTOMOUNT |
| Don't automount the terminal ("basename") component of |
| .I pathname |
| if it is a directory that is an automount point. |
| This allows the caller to gather attributes of an automount point |
| (rather than the location it would mount). |
| This flag can be used in tools that scan directories |
| to prevent mass-automounting of a directory of automount points. |
| The |
| .B AT_NO_AUTOMOUNT |
| flag has no effect if the mount point has already been mounted over. |
| This flag is Linux-specific; define |
| .B _GNU_SOURCE |
| .\" Before glibc 2.16, defining _ATFILE_SOURCE sufficed |
| to obtain its definition. |
| .TP |
| .B AT_SYMLINK_NOFOLLOW |
| If |
| .I pathname |
| is a symbolic link, do not dereference it: |
| instead return information about the link itself, like |
| .BR lstat (2). |
| .PP |
| .I flags |
| can also be used to control what sort of synchronization the kernel will do |
| when querying a file on a remote filesystem. |
| This is done by ORing in one of the following values: |
| .TP |
| .B AT_STATX_SYNC_AS_STAT |
| Do whatever |
| .BR stat (2) |
| does. |
| This is the default and is very much filesystem-specific. |
| .TP |
| .B AT_STATX_FORCE_SYNC |
| Force the attributes to be synchronized with the server. |
| This may require that |
| a network filesystem perform a data writeback to get the timestamps correct. |
| .TP |
| .B AT_STATX_DONT_SYNC |
| Don't synchronize anything, but rather just take whatever |
| the system has cached if possible. |
| This may mean that the information returned is approximate, but, |
| on a network filesystem, it may not involve a round trip to the server - even |
| if no lease is held. |
| .PP |
| The |
| .I mask |
| argument to |
| .BR statx () |
| is used to tell the kernel which fields the caller is interested in. |
| .I mask |
| is an ORed combination of the following constants: |
| .PP |
| .in +4n |
| .TS |
| lB l. |
| STATX_TYPE Want stx_mode & S_IFMT |
| STATX_MODE Want stx_mode & ~S_IFMT |
| STATX_NLINK Want stx_nlink |
| STATX_UID Want stx_uid |
| STATX_GID Want stx_gid |
| STATX_ATIME Want stx_atime |
| STATX_MTIME Want stx_mtime |
| STATX_CTIME Want stx_ctime |
| STATX_INO Want stx_ino |
| STATX_SIZE Want stx_size |
| STATX_BLOCKS Want stx_blocks |
| STATX_BASIC_STATS [All of the above] |
| STATX_BTIME Want stx_btime |
| STATX_ALL [All currently available fields] |
| .TE |
| .in |
| .PP |
| Note that, in general, the kernel does |
| .I not |
| reject values in |
| .I mask |
| other than the above. |
| (For an exception, see |
| .B EINVAL |
| in errors.) |
| Instead, it simply informs the caller which values are supported |
| by this kernel and filesystem via the |
| .I statx.stx_mask |
| field. |
| Therefore, |
| .I "do not" |
| simply set |
| .I mask |
| to |
| .B UINT_MAX |
| (all bits set), |
| as one or more bits may, in the future, be used to specify an |
| extension to the buffer. |
| .SS |
| The returned information |
| The status information for the target file is returned in the |
| .I statx |
| structure pointed to by |
| .IR statxbuf . |
| Included in this is |
| .I stx_mask |
| which indicates what other information has been returned. |
| .I stx_mask |
| has the same format as the |
| .I mask |
| argument and bits are set in it to indicate |
| which fields have been filled in. |
| .PP |
| It should be noted that the kernel may return fields that weren't |
| requested and may fail to return fields that were requested, |
| depending on what the backing filesystem supports. |
| (Fields that are given values despite being unrequested can just be ignored.) |
| In either case, |
| .I stx_mask |
| will not be equal |
| .IR mask . |
| .PP |
| If a filesystem does not support a field or if it has |
| an unrepresentable value (for instance, a file with an exotic type), |
| then the mask bit corresponding to that field will be cleared in |
| .I stx_mask |
| even if the user asked for it and a dummy value will be filled in for |
| compatibility purposes if one is available (e.g., a dummy UID and GID may be |
| specified to mount under some circumstances). |
| .PP |
| A filesystem may also fill in fields that the caller didn't ask for if it has |
| values for them available and the information is available at no extra cost. |
| If this happens, the corresponding bits will be set in |
| .IR stx_mask . |
| .PP |
| .\" Background: inode attributes are modified with i_mutex held, but |
| .\" read by stat() without taking the mutex. |
| .IR Note : |
| for performance and simplicity reasons, different fields in the |
| .I statx |
| structure may contain state information from different moments |
| during the execution of the system call. |
| For example, if |
| .IR stx_mode |
| or |
| .IR stx_uid |
| is changed by another process by calling |
| .BR chmod (2) |
| or |
| .BR chown (2), |
| .BR stat () |
| might return the old |
| .I stx_mode |
| together with the new |
| .IR stx_uid , |
| or the old |
| .I stx_uid |
| together with the new |
| .IR stx_mode . |
| .PP |
| Apart from |
| .I stx_mask |
| (which is described above), the fields in the |
| .I statx |
| structure are: |
| .TP |
| .I stx_blksize |
| The "preferred" block size for efficient filesystem I/O. |
| (Writing to a file in |
| smaller chunks may cause an inefficient read-modify-rewrite.) |
| .TP |
| .I stx_attributes |
| Further status information about the file (see below for more information). |
| .TP |
| .I stx_nlink |
| The number of hard links on a file. |
| .TP |
| .I stx_uid |
| This field contains the user ID of the owner of the file. |
| .TP |
| .I stx_gid |
| This field contains the ID of the group owner of the file. |
| .TP |
| .I stx_mode |
| The file type and mode. |
| See |
| .BR inode (7) |
| for details. |
| .TP |
| .I stx_ino |
| The inode number of the file. |
| .TP |
| .I stx_size |
| The size of the file (if it is a regular file or a symbolic link) in bytes. |
| The size of a symbolic link is the length of the pathname it contains, |
| without a terminating null byte. |
| .TP |
| .I stx_blocks |
| The number of blocks allocated to the file on the medium, in 512-byte units. |
| (This may be smaller than |
| .IR stx_size /512 |
| when the file has holes.) |
| .TP |
| .I stx_attributes_mask |
| A mask indicating which bits in |
| .IR stx_attributes |
| are supported by the VFS and the filesystem. |
| .TP |
| .I stx_atime |
| The file's last access timestamp. |
| .TP |
| .I stx_btime |
| The file's creation timestamp. |
| .TP |
| .I stx_ctime |
| The file's last status change timestamp. |
| .TP |
| .I stx_mtime |
| The file's last modification timestamp. |
| .TP |
| .IR stx_dev_major " and " stx_dev_minor |
| The device on which this file (inode) resides. |
| .TP |
| .IR stx_rdev_major " and " stx_rdev_minor |
| The device that this file (inode) represents if the file is of block or |
| character device type. |
| .PP |
| For further information on the above fields, see |
| .BR inode (7). |
| .\" |
| .SS File attributes |
| The |
| .I stx_attributes |
| field contains a set of ORed flags that indicate additional attributes |
| of the file. |
| Note that any attribute that is not indicated as supported by |
| .I stx_attributes_mask |
| has no usable value here. |
| The bits in |
| .I stx_attributes_mask |
| correspond bit-by-bit to |
| .IR stx_attributes . |
| .PP |
| The flags are as follows: |
| .TP |
| .B STATX_ATTR_COMPRESSED |
| The file is compressed by the filesystem and may take extra resources |
| to access. |
| .TP |
| .B STATX_ATTR_IMMUTABLE |
| The file cannot be modified: it cannot be deleted or renamed, |
| no hard links can be created to this file and no data can be written to it. |
| See |
| .BR chattr (1). |
| .TP |
| .B STATX_ATTR_APPEND |
| The file can only be opened in append mode for writing. |
| Random access writing |
| is not permitted. |
| See |
| .BR chattr (1). |
| .TP |
| .B STATX_ATTR_NODUMP |
| File is not a candidate for backup when a backup program such as |
| .BR dump (8) |
| is run. |
| See |
| .BR chattr (1). |
| .TP |
| .B STATX_ATTR_ENCRYPTED |
| A key is required for the file to be encrypted by the filesystem. |
| .TP |
| .BR STATX_ATTR_VERITY " (since Linux 5.5)" |
| .\" commit 3ad2522c64cff1f5aebb987b00683268f0cc7c29 |
| The file has fs-verity enabled. |
| It cannot be written to, and all reads from it will be verified |
| against a cryptographic hash that covers the |
| entire file (e.g., via a Merkle tree). |
| .SH RETURN VALUE |
| On success, zero is returned. |
| On error, \-1 is returned, and |
| .I errno |
| is set appropriately. |
| .SH ERRORS |
| .TP |
| .B EACCES |
| Search permission is denied for one of the directories |
| in the path prefix of |
| .IR pathname . |
| (See also |
| .BR path_resolution (7).) |
| .TP |
| .B EBADF |
| .I dirfd |
| is not a valid open file descriptor. |
| .TP |
| .B EFAULT |
| .I pathname |
| or |
| .I statxbuf |
| is NULL or points to a location outside the process's |
| accessible address space. |
| .TP |
| .B EINVAL |
| Invalid flag specified in |
| .IR flags . |
| .TP |
| .B EINVAL |
| Reserved flag specified in |
| .IR mask . |
| (Currently, there is one such flag, designated by the constant |
| .BR STATX__RESERVED , |
| with the value 0x80000000U.) |
| .TP |
| .B ELOOP |
| Too many symbolic links encountered while traversing the pathname. |
| .TP |
| .B ENAMETOOLONG |
| .I pathname |
| is too long. |
| .TP |
| .B ENOENT |
| A component of |
| .I pathname |
| does not exist, or |
| .I pathname |
| is an empty string and |
| .B AT_EMPTY_PATH |
| was not specified in |
| .IR flags . |
| .TP |
| .B ENOMEM |
| Out of memory (i.e., kernel memory). |
| .TP |
| .B ENOTDIR |
| A component of the path prefix of |
| .I pathname |
| is not a directory or |
| .I pathname |
| is relative and |
| .I dirfd |
| is a file descriptor referring to a file other than a directory. |
| .SH VERSIONS |
| .BR statx () |
| was added to Linux in kernel 4.11; library support was added in glibc 2.28. |
| .SH CONFORMING TO |
| .BR statx () |
| is Linux-specific. |
| .SH SEE ALSO |
| .BR ls (1), |
| .BR stat (1), |
| .BR access (2), |
| .BR chmod (2), |
| .BR chown (2), |
| .BR readlink (2), |
| .BR stat (2), |
| .BR utime (2), |
| .BR capabilities (7), |
| .BR inode (7), |
| .BR symlink (7) |