mirror of https://github.com/mkerrisk/man-pages
576 lines
15 KiB
Groff
576 lines
15 KiB
Groff
.\" 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 2021-03-22 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
statx \- get file status (extended)
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.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 *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:
|
|
.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\(aqs 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 & \(tiS_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).
|
|
.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.
|
|
.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 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)
|