diff options
Diffstat (limited to 'man/man2/statx.2')
| -rw-r--r-- | man/man2/statx.2 | 614 |
1 files changed, 614 insertions, 0 deletions
diff --git a/man/man2/statx.2 b/man/man2/statx.2 new file mode 100644 index 000000000..0dcf7e20b --- /dev/null +++ b/man/man2/statx.2 @@ -0,0 +1,614 @@ +'\" t +.\" 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> +.\" +.\" SPDX-License-Identifier: Linux-man-pages-copyleft +.\" +.TH statx 2 (date) "Linux man-pages (unreleased)" +.SH NAME +statx \- get file status (extended) +.SH LIBRARY +Standard C library +.RI ( libc ", " \-lc ) +.SH SYNOPSIS +.nf +.BR "#define _GNU_SOURCE " "/* See feature_test_macros(7) */" +.BR "#include <fcntl.h> " "/* Definition of " AT_* " constants */" +.B #include <sys/stat.h> +.P +.BI "int statx(int " dirfd ", const char *restrict " pathname ", int " flags , +.BI " unsigned int " mask ", struct statx *restrict " 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: +.P +.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\[aq]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 */ +\& + __u64 stx_mnt_id; /* Mount ID */ +\& + /* Direct I/O alignment restrictions */ + __u32 stx_dio_mem_align; + __u32 stx_dio_offset_align; +}; +.EE +.in +.P +The file timestamps are structures of the following type: +.P +.in +4n +.EX +struct statx_timestamp { + __s64 tv_sec; /* Seconds since the Epoch (UNIX time) */ + __u32 tv_nsec; /* Nanoseconds since tv_sec */ +}; +.EE +.in +.P +(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. +.P +.BR statx () +uses +.IR pathname , +.IR dirfd , +and +.I 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 +.I 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 . +(See +.BR openat (2) +for an explanation of why this is useful.) +.TP +By file descriptor +If +.I pathname +is an empty string and the +.B AT_EMPTY_PATH +flag is specified in +.I flags +(see below), +then the target file is the one referred to by the file descriptor +.IR dirfd . +.P +.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 +.B AT_EMPTY_PATH +.\" commit 65cfc6722361570bfe255698d9cd4dccaf47570d +If +.I pathname +is an empty string, operate on the file referred to by +.I 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. +.TP +.B 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 has no effect if the mount point has already been mounted over. +.IP +The +.B AT_NO_AUTOMOUNT +flag can be used in tools that scan directories +to prevent mass-automounting of a directory of automount points. +.IP +All of +.BR stat (2), +.BR lstat (2), +and +.BR fstatat (2) +act as though +.B AT_NO_AUTOMOUNT +was set. +.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). +.P +.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. +.P +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: +.P +.in +4n +.TS +lB l. +STATX_TYPE Want stx_mode & S_IFMT +STATX_MODE Want stx_mode & \[ti]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 The same as STATX_BASIC_STATS | STATX_BTIME. + It is deprecated and should not be used. +STATX_MNT_ID Want stx_mnt_id (since Linux 5.8) +STATX_DIOALIGN Want stx_dio_mem_align and stx_dio_offset_align + (since Linux 6.1; support varies by filesystem) +.TE +.in +.P +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. +.P +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 . +.P +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). +.P +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 . +.P +.\" 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 +.I stx_mode +or +.I 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 . +.P +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 +.I 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. +.TP +.I stx_mnt_id +.\" commit fa2fcf4f1df1559a0a4ee0f46915b496cc2ebf60 +The mount ID of the mount containing the file. +This is the same number reported by +.BR name_to_handle_at (2) +and corresponds to the number in the first field in one of the records in +.IR /proc/self/mountinfo . +.TP +.I stx_dio_mem_align +The alignment (in bytes) required for user memory buffers for direct I/O +.RB ( O_DIRECT ) +on this file, +or 0 if direct I/O is not supported on this file. +.IP +.B STATX_DIOALIGN +.RI ( stx_dio_mem_align +and +.IR stx_dio_offset_align ) +is supported on block devices since Linux 6.1. +The support on regular files varies by filesystem; +it is supported by ext4, f2fs, and xfs since Linux 6.1. +.TP +.I stx_dio_offset_align +The alignment (in bytes) required for file offsets and I/O segment lengths +for direct I/O +.RB ( O_DIRECT ) +on this file, +or 0 if direct I/O is not supported on this file. +This will only be nonzero if +.I stx_dio_mem_align +is nonzero, and vice versa. +.P +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 . +.P +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). +.TP +.BR STATX_ATTR_DAX " (since Linux 5.8)" +The file is in the DAX (cpu direct access) state. +DAX state attempts to +minimize software cache effects for both I/O and memory mappings of this file. +It requires a file system which has been configured to support DAX. +.IP +DAX generally assumes all accesses are via CPU load / store instructions +which can minimize overhead for small accesses, +but may adversely affect CPU utilization for large transfers. +.IP +File I/O is done directly to/from user-space buffers and memory mapped I/O may +be performed with direct memory mappings that bypass the kernel page cache. +.IP +While the DAX property tends to result in data being transferred synchronously, +it does not give the same guarantees as the +.B O_SYNC +flag (see +.BR open (2)), +where data and the necessary metadata are transferred together. +.IP +A DAX file may support being mapped with the +.B MAP_SYNC +flag, which enables a +program to use CPU cache flush instructions to persist CPU store operations +without an explicit +.BR fsync (2). +See +.BR mmap (2) +for more information. +.TP +.BR STATX_ATTR_MOUNT_ROOT " (since Linux 5.8)" +.\" commit 80340fe3605c0e78cfe496c3b3878be828cfdbfe +The file is the root of a mount. +.SH RETURN VALUE +On success, zero is returned. +On error, \-1 is returned, and +.I errno +is set to indicate the error. +.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 pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid 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 STANDARDS +Linux. +.SH HISTORY +Linux 4.11, +glibc 2.28. +.SH SEE ALSO +.BR ls (1), +.BR stat (1), +.BR access (2), +.BR chmod (2), +.BR chown (2), +.BR name_to_handle_at (2), +.BR readlink (2), +.BR stat (2), +.BR utime (2), +.BR proc (5), +.BR capabilities (7), +.BR inode (7), +.BR symlink (7) |