Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 614 insertions, 0 deletions

diff --git a/man/man2/statx.2 b/man/man2/statx.2
new file mode 100644
index 0000000..855fb6e
--- /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 2024-05-02 "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)