statx (2) - Linux Manuals
statx: get file status (extended)
Command to display statx manual in Linux: $ man 2 statx
NAME
statx - get file status (extended)
SYNOPSIS
#include <sys/types.h>
#include <sys/stat.h>
#include <unistd.h>
#include <fcntl.h> /* Definition of AT_* constants */
int statx(int dirfd, const char *pathname, int flags,
unsigned int mask, struct statx *statxbuf);
DESCRIPTION
This function returns information about a file, storing it in the buffer
pointed to by
statxbuf.
The returned buffer is a structure of the following type:
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 */
};
The file timestamps are structures of the following type:
struct statx_timestamp {
__s64 tv_sec; /* Seconds since the Epoch (UNIX time) */
__u32 tv_nsec; /* Nanoseconds since tv_sec */
};
(Note that reserved space and padding is omitted.)
Invoking statx():
To access a file's status, no permissions are required on the file itself,
but in the case of
statx()
with a pathname,
execute (search) permission is required on all of the directories in
pathname
that lead to the file.
statx()
uses
pathname,
dirfd,
and
flags
to identify the target file in one of the following ways:
- An absolute pathname
-
If
pathname
begins with a slash,
then it is an absolute pathname that identifies the target file.
In this case,
dirfd
is ignored.
- A relative pathname
-
If
pathname
is a string that begins with a character other than a slash and
dirfd
is
AT_FDCWD,
then
pathname
is a relative pathname that is interpreted relative to the process's
current working directory.
- A directory-relative pathname
-
If
pathname
is a string that begins with a character other than a slash and
dirfd
is a file descriptor that refers to a directory, then
pathname
is a relative pathname that is interpreted relative to the directory
referred to by
dirfd.
- By file descriptor
-
If
pathname
is an empty string and the
AT_EMPTY_PATH
flag is specified in
flags
(see below),
then the target file is the one referred to by the file descriptor
dirfd.
flags
can be used to influence a pathname-based lookup.
A value for
flags
is constructed by ORing together zero or more of the following constants:
- AT_EMPTY_PATH
-
If
pathname
is an empty string, operate on the file referred to by
dirfd
(which may have been obtained using the