diff options
Diffstat (limited to 'man2/statx.2')
| -rw-r--r-- | man2/statx.2 | 614 |
1 files changed, 0 insertions, 614 deletions
diff --git a/man2/statx.2 b/man2/statx.2 deleted file mode 100644 index 0dcf7e20b..000000000 --- a/man2/statx.2 +++ /dev/null @@ -1,614 +0,0 @@ -'\" 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) |