2017-04-06 14:15:45 +00:00
|
|
|
'\" 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>
|
|
|
|
.\"
|
|
|
|
.\" %%%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 2017-03-07 "Linux" "Linux Programmer's Manual"
|
|
|
|
.SH NAME
|
|
|
|
statx \- Get file status (extended)
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.nf
|
|
|
|
.B #include <sys/types.h>
|
|
|
|
.br
|
|
|
|
.B #include <sys/stat.h>
|
|
|
|
.br
|
|
|
|
.B #include <unistd.h>
|
|
|
|
.br
|
|
|
|
.BR "#include <fcntl.h> " "/* Definition of AT_* constants */"
|
|
|
|
.sp
|
|
|
|
.BI "int statx(int " dirfd ", const char *" pathname ", int " flags ","
|
|
|
|
.BI " unsigned int " mask ", struct statx *" buf );
|
|
|
|
.fi
|
|
|
|
.sp
|
|
|
|
.in -4n
|
|
|
|
Feature Test Macro Requirements for glibc (see
|
|
|
|
.BR feature_test_macros (7)):
|
|
|
|
.in
|
|
|
|
.ad l
|
|
|
|
.PD 0
|
|
|
|
.sp
|
|
|
|
.RS 4
|
|
|
|
<unknown as yet>
|
|
|
|
.RE
|
|
|
|
.PD
|
|
|
|
.ad
|
|
|
|
.SH DESCRIPTION
|
|
|
|
.PP
|
|
|
|
This function returns information about a file, storing it in the buffer
|
|
|
|
pointed to by
|
|
|
|
.IR buf .
|
|
|
|
The buffer is filled in according to the following type:
|
|
|
|
.PP
|
|
|
|
.in +4n
|
|
|
|
.nf
|
|
|
|
struct statx {
|
2017-04-21 14:42:39 +00:00
|
|
|
__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 */
|
|
|
|
|
|
|
|
/* 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 device, then the next two feilds
|
|
|
|
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
|
|
|
|
contain the filesystem where the file resides */
|
|
|
|
__u32 stx_dev_major; /* Major ID */
|
|
|
|
__u32 stx_dev_minor; /* Minor ID */
|
2017-04-06 14:15:45 +00:00
|
|
|
};
|
|
|
|
.fi
|
|
|
|
.in
|
|
|
|
.PP
|
2017-04-21 14:42:39 +00:00
|
|
|
The file timestamps are structures of the following type:
|
2017-04-06 14:15:45 +00:00
|
|
|
.PP
|
|
|
|
.in +4n
|
|
|
|
.nf
|
|
|
|
struct statx_timestamp {
|
2017-04-21 14:42:39 +00:00
|
|
|
__s64 tv_sec; /* Seconds since the Epoch (UNIX time) */
|
|
|
|
__s32 tv_nsec; /* Nanoseconds before or since tv_sec */
|
2017-04-06 14:15:45 +00:00
|
|
|
};
|
|
|
|
.fi
|
|
|
|
.in
|
|
|
|
.PP
|
|
|
|
(Note that reserved space and padding is omitted)
|
|
|
|
.SS
|
|
|
|
Invoking \fBstatx\fR():
|
|
|
|
.PP
|
2017-04-21 14:44:51 +00:00
|
|
|
To access a file's status, no permissions are required on the file itself,
|
|
|
|
but in the case of
|
2017-04-06 14:15:45 +00:00
|
|
|
.BR statx ()
|
2017-04-21 14:44:51 +00:00
|
|
|
with a path,
|
|
|
|
execute (search) permission is required on all of the directories in
|
2017-04-06 14:15:45 +00:00
|
|
|
.I pathname
|
|
|
|
that lead to the file.
|
|
|
|
.PP
|
|
|
|
.BR statx ()
|
|
|
|
uses
|
2017-04-21 14:42:39 +00:00
|
|
|
.IR pathname ,
|
|
|
|
.IR dirfd ,
|
|
|
|
and
|
|
|
|
.IR flags
|
2017-04-06 14:15:45 +00:00
|
|
|
to locate the target file in one of a variety of ways:
|
|
|
|
.TP
|
|
|
|
[*] By absolute path.
|
|
|
|
.I pathname
|
|
|
|
points to an absolute path and
|
|
|
|
.I dirfd
|
2017-04-21 14:44:51 +00:00
|
|
|
is ignored.
|
|
|
|
The file is looked up by name, starting from the root of the
|
2017-04-06 14:15:45 +00:00
|
|
|
filesystem as seen by the calling process.
|
|
|
|
.TP
|
|
|
|
[*] By cwd-relative path.
|
|
|
|
.I pathname
|
|
|
|
points to a relative path and
|
2017-04-21 14:42:39 +00:00
|
|
|
.IR dirfd
|
|
|
|
is
|
|
|
|
.BR AT_FDCWD .
|
2017-04-06 14:15:45 +00:00
|
|
|
The file is looked up by name, starting from the current working directory.
|
|
|
|
.TP
|
|
|
|
[*] By dir-relative path.
|
|
|
|
.I pathname
|
|
|
|
points to relative path and
|
|
|
|
.I dirfd
|
2017-04-21 14:44:51 +00:00
|
|
|
indicates a file descriptor pointing to a directory.
|
|
|
|
The file is looked up by name, starting from the directory specified by
|
2017-04-06 14:15:45 +00:00
|
|
|
.IR dirfd .
|
|
|
|
.TP
|
|
|
|
[*] By file descriptor.
|
|
|
|
.IR pathname " is " NULL " and " dirfd
|
2017-04-21 14:44:51 +00:00
|
|
|
indicates a file descriptor.
|
|
|
|
The file attached to the file descriptor is queried directly.
|
|
|
|
The file descriptor may point to any type of file, not just
|
2017-04-06 14:15:45 +00:00
|
|
|
a directory.
|
|
|
|
.PP
|
|
|
|
.I flags
|
2017-04-21 14:44:51 +00:00
|
|
|
can be used to influence a path-based lookup.
|
|
|
|
A value for
|
2017-04-06 14:15:45 +00:00
|
|
|
.I flags
|
|
|
|
is constructed by OR'ing 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).
|
|
|
|
If
|
|
|
|
.I dirfd
|
|
|
|
is
|
|
|
|
.BR AT_FDCWD ,
|
|
|
|
the call operates on the current working directory.
|
|
|
|
In this case,
|
|
|
|
.I dirfd
|
|
|
|
can refer to any type of file, not just a directory.
|
|
|
|
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
|
2017-04-21 14:42:39 +00:00
|
|
|
.BR lstat (2).
|
2017-04-06 14:15:45 +00:00
|
|
|
.PP
|
|
|
|
.I flags
|
2017-04-21 14:44:51 +00:00
|
|
|
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 OR'ing in one of the following values:
|
2017-04-06 14:15:45 +00:00
|
|
|
.TP
|
|
|
|
AT_STATX_SYNC_AS_STAT
|
|
|
|
Do whatever
|
2017-04-21 14:42:39 +00:00
|
|
|
.BR stat (2)
|
2017-04-21 14:44:51 +00:00
|
|
|
does.
|
|
|
|
This is the default and is very much filesystem specific.
|
2017-04-06 14:15:45 +00:00
|
|
|
.TP
|
|
|
|
AT_STATX_FORCE_SYNC
|
2017-04-21 14:44:51 +00:00
|
|
|
Force the attributes to be synchronised with the server.
|
|
|
|
This may require that
|
2017-04-06 14:15:45 +00:00
|
|
|
a network filesystem perform a data writeback to get the timestamps correct.
|
|
|
|
.TP
|
|
|
|
AT_STATX_DONT_SYNC
|
|
|
|
Don't synchronise anything, but rather just take whatever the system has cached
|
2017-04-21 14:44:51 +00:00
|
|
|
if possible.
|
|
|
|
This may mean that the information returned is approximate, but,
|
2017-04-06 14:15:45 +00:00
|
|
|
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 OR'ed combination of the following constants:
|
|
|
|
.PP
|
|
|
|
.in +4n
|
|
|
|
.TS
|
|
|
|
lB l.
|
|
|
|
STATX_TYPE Want stx_mode & S_IFMT
|
|
|
|
STATX_MODE Want stx_mode & ~S_IFMT
|
|
|
|
STATX_NLINK Want stx_nlink
|
|
|
|
STATX_UID Want stx_uid
|
|
|
|
STATX_GID Want stx_gid
|
|
|
|
STATX_ATIME Want stx_atime{,_ns}
|
|
|
|
STATX_MTIME Want stx_mtime{,_ns}
|
|
|
|
STATX_CTIME Want stx_ctime{,_ns}
|
|
|
|
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{,_ns}
|
|
|
|
STATX_ALL [All currently available fields]
|
|
|
|
.TE
|
|
|
|
.in
|
|
|
|
.PP
|
|
|
|
.B "Do not"
|
|
|
|
simply set
|
|
|
|
.I mask
|
|
|
|
to UINT_MAX as one or more bits may, in the future, be used to specify an
|
|
|
|
extension to the buffer.
|
|
|
|
.SS
|
|
|
|
The returned information
|
|
|
|
.PP
|
|
|
|
The status information for the target file is returned in the
|
|
|
|
.I statx
|
|
|
|
structure pointed to by
|
|
|
|
.IR buf .
|
|
|
|
Included in this is
|
|
|
|
.I stx_mask
|
|
|
|
which indicates what other information has been returned.
|
|
|
|
.I stx_mask
|
|
|
|
has the same format as the 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
|
2017-04-21 14:44:51 +00:00
|
|
|
filesystem supports.
|
|
|
|
In either case,
|
2017-04-06 14:15:45 +00:00
|
|
|
.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
|
2017-04-21 14:44:51 +00:00
|
|
|
values for them available at no extra cost.
|
|
|
|
If this happens, the corresponding bits will be set in
|
2017-04-06 14:15:45 +00:00
|
|
|
.IR stx_mask .
|
|
|
|
.PP
|
|
|
|
.\" Background: inode attributes are modified with i_mutex held, but
|
|
|
|
.\" read by stat() without taking the mutex.
|
|
|
|
.I 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 stx_mask (which is described above), the fields in the
|
|
|
|
.I statx
|
|
|
|
structure are:
|
|
|
|
.TP
|
|
|
|
.I stx_mode
|
2017-04-21 14:44:51 +00:00
|
|
|
The file type and mode.
|
|
|
|
This is described in more detail below.
|
2017-04-06 14:15:45 +00:00
|
|
|
.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_blksize
|
2017-04-21 14:44:51 +00:00
|
|
|
The "preferred" blocksize for efficient filesystem I/O.
|
|
|
|
(Writing to a file in
|
2017-04-06 14:15:45 +00:00
|
|
|
smaller chunks may cause an inefficient read-modify-rewrite.)
|
|
|
|
.TP
|
|
|
|
.I stx_nlink
|
|
|
|
The number of hard links on a file.
|
|
|
|
.TP
|
|
|
|
.I stx_uid
|
|
|
|
The user ID of the file's owner.
|
|
|
|
.TP
|
|
|
|
.I stx_gid
|
|
|
|
The ID of the group that may access the file.
|
|
|
|
.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_attributes
|
|
|
|
Further status information about the file (see below for more information).
|
|
|
|
.TP
|
|
|
|
.I stx_atime
|
|
|
|
The file's last access timestamp.
|
|
|
|
This field is changed by file accesses, for example, by
|
|
|
|
.BR execve (2),
|
|
|
|
.BR mknod (2),
|
|
|
|
.BR pipe (2),
|
|
|
|
.BR utime (2),
|
|
|
|
and
|
|
|
|
.BR read (2)
|
|
|
|
(of more than zero bytes).
|
|
|
|
Other routines, such as
|
|
|
|
.BR mmap (2),
|
|
|
|
may or may not update it.
|
|
|
|
.TP
|
|
|
|
.I stx_btime
|
2017-04-21 14:44:51 +00:00
|
|
|
The file's creation timestamp.
|
|
|
|
This is set on file creation and not changed subsequently.
|
2017-04-06 14:15:45 +00:00
|
|
|
.TP
|
|
|
|
.I stx_ctime
|
2017-04-21 14:44:51 +00:00
|
|
|
The file's last status change timestamp.
|
|
|
|
This field is changed by writing or
|
2017-04-06 14:15:45 +00:00
|
|
|
by setting inode information (i.e., owner, group, link count, mode, etc.).
|
|
|
|
.TP
|
|
|
|
.I stx_mtime
|
2017-04-21 14:44:51 +00:00
|
|
|
The file's last modification timestamp.
|
|
|
|
This is changed by file modifications,
|
2017-04-06 14:15:45 +00:00
|
|
|
for example, by
|
|
|
|
.BR mknod (2),
|
|
|
|
.BR truncate (2),
|
|
|
|
.BR utime (2),
|
|
|
|
and
|
|
|
|
.BR write (2)
|
2017-04-21 14:44:51 +00:00
|
|
|
(of more than zero bytes).
|
|
|
|
Moreover, the modification time of a directory is
|
|
|
|
changed by the creation or deletion of files in that directory.
|
|
|
|
This field is
|
2017-04-06 14:15:45 +00:00
|
|
|
.I not
|
|
|
|
changed for changes in owner, group, hard link count, or mode.
|
|
|
|
.PP
|
2017-04-21 14:44:51 +00:00
|
|
|
Not all of the Linux filesystems implement all of the timestamp fields.
|
|
|
|
Some filesystems allow mounting in such a way that file and/or
|
|
|
|
directory accesses do not cause an update of the
|
2017-04-06 14:15:45 +00:00
|
|
|
.I stx_atime
|
|
|
|
field.
|
|
|
|
(See
|
|
|
|
.IR noatime ,
|
|
|
|
.IR nodiratime ,
|
|
|
|
and
|
|
|
|
.I relatime
|
|
|
|
in
|
|
|
|
.BR mount (8),
|
|
|
|
and related information in
|
|
|
|
.BR mount (2).)
|
|
|
|
In addition,
|
|
|
|
.I stx_atime
|
|
|
|
is not updated if a file is opened with the
|
|
|
|
.BR O_NOATIME ;
|
|
|
|
see
|
|
|
|
.BR open (2).
|
2017-04-21 14:44:51 +00:00
|
|
|
.\"
|
2017-04-06 14:15:45 +00:00
|
|
|
.SS File attributes
|
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.I stx_attributes
|
|
|
|
field contains a set of OR'ed flags that indicate additional attributes of the
|
|
|
|
file:
|
|
|
|
.TP
|
|
|
|
STATX_ATTR_COMPRESSED
|
|
|
|
The file is compressed by the fs and may take extra resources to access.
|
|
|
|
.TP
|
|
|
|
STATX_ATTR_IMMUTABLE
|
|
|
|
The file cannot be modified: it cannot be deleted or renamed, no hard links can
|
2017-04-21 14:44:51 +00:00
|
|
|
be created to this file and no data can be written to it.
|
|
|
|
See chattr(1).
|
2017-04-06 14:15:45 +00:00
|
|
|
.TP
|
|
|
|
STATX_ATTR_APPEND
|
2017-04-21 14:44:51 +00:00
|
|
|
The file can only be opened in append mode for writing.
|
|
|
|
Random access writing
|
|
|
|
is not permitted.
|
|
|
|
See chattr(1).
|
2017-04-06 14:15:45 +00:00
|
|
|
.TP
|
|
|
|
STATX_ATTR_NODUMP
|
|
|
|
File is not a candidate for backup when a backup program such as dump(8) is
|
2017-04-21 14:44:51 +00:00
|
|
|
run.
|
|
|
|
See chattr(1).
|
2017-04-06 14:15:45 +00:00
|
|
|
.TP
|
|
|
|
STATX_ATTR_ENCRYPTED
|
|
|
|
A key is required for the file to be encrypted by the filesystem.
|
|
|
|
.SS File type and mode
|
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.I stx_mode
|
2017-04-21 14:44:51 +00:00
|
|
|
field contains the combined file type and mode.
|
|
|
|
POSIX refers to the bits in
|
2017-04-06 14:15:45 +00:00
|
|
|
this field corresponding to the mask
|
|
|
|
.B S_IFMT
|
|
|
|
(see below) as the
|
|
|
|
.IR "file type" ,
|
|
|
|
the 12 bits corresponding to the mask 07777 as the
|
|
|
|
.IR "file mode bits"
|
|
|
|
and the least significant 9 bits (0777) as the
|
|
|
|
.IR "file permission bits" .
|
|
|
|
.IP
|
|
|
|
The following mask values are defined for the file type of the
|
|
|
|
.I stx_mode
|
|
|
|
field:
|
|
|
|
.in +4n
|
|
|
|
.TS
|
|
|
|
lB l l.
|
|
|
|
S_IFMT 0170000 bit mask for the file type bit field
|
|
|
|
|
|
|
|
S_IFSOCK 0140000 socket
|
|
|
|
S_IFLNK 0120000 symbolic link
|
|
|
|
S_IFREG 0100000 regular file
|
|
|
|
S_IFBLK 0060000 block device
|
|
|
|
S_IFDIR 0040000 directory
|
|
|
|
S_IFCHR 0020000 character device
|
|
|
|
S_IFIFO 0010000 FIFO
|
|
|
|
.TE
|
|
|
|
.in
|
|
|
|
.IP
|
|
|
|
Note that
|
|
|
|
.I stx_mode
|
|
|
|
has two mask flags covering it: one for the type and one for the mode bits.
|
|
|
|
.PP
|
|
|
|
To test for a regular file (for example), one could write:
|
|
|
|
.nf
|
|
|
|
.in +4n
|
|
|
|
statx(AT_FDCWD, pathname, 0, STATX_TYPE, &sb);
|
|
|
|
if ((sb.stx_mask & STATX_TYPE) && (sb.stx_mode & S_IFMT) == S_IFREG) {
|
|
|
|
/* Handle regular file */
|
|
|
|
}
|
|
|
|
.in
|
|
|
|
.fi
|
|
|
|
.PP
|
|
|
|
Because tests of the above form are common, additional macros are defined by
|
|
|
|
POSIX to allow the test of the file type in
|
|
|
|
.I stx_mode
|
|
|
|
to be written more concisely:
|
|
|
|
.RS 4
|
|
|
|
.TS
|
|
|
|
lB l.
|
|
|
|
\fBS_ISREG\fR(m) Is it a regular file?
|
|
|
|
\fBS_ISDIR\fR(m) Is it a directory?
|
|
|
|
\fBS_ISCHR\fR(m) Is it a character device?
|
|
|
|
\fBS_ISBLK\fR(m) Is it a block device?
|
|
|
|
\fBS_ISFIFO\fR(m) Is it a FIFO (named pipe)?
|
|
|
|
\fBS_ISLNK\fR(m) Is it a symbolic link? (Not in POSIX.1-1996.)
|
|
|
|
\fBS_ISSOCK\fR(m) Is it a socket? (Not in POSIX.1-1996.)
|
|
|
|
.TE
|
|
|
|
.RE
|
|
|
|
.PP
|
|
|
|
The preceding code snippet could thus be rewritten as:
|
|
|
|
|
|
|
|
.nf
|
|
|
|
.in +4n
|
|
|
|
statx(AT_FDCWD, pathname, 0, STATX_TYPE, &sb);
|
|
|
|
if ((sb.stx_mask & STATX_TYPE) && S_ISREG(sb.stx_mode)) {
|
|
|
|
/* Handle regular file */
|
|
|
|
}
|
|
|
|
.in
|
|
|
|
.fi
|
|
|
|
.PP
|
|
|
|
The definitions of most of the above file type test macros
|
|
|
|
are provided if any of the following feature test macros is defined:
|
|
|
|
.BR _BSD_SOURCE
|
|
|
|
(in glibc 2.19 and earlier),
|
|
|
|
.BR _SVID_SOURCE
|
|
|
|
(in glibc 2.19 and earlier),
|
|
|
|
or
|
|
|
|
.BR _DEFAULT_SOURCE
|
|
|
|
(in glibc 2.20 and later).
|
|
|
|
In addition, definitions of all of the above macros except
|
|
|
|
.BR S_IFSOCK
|
|
|
|
and
|
|
|
|
.BR S_ISSOCK ()
|
|
|
|
are provided if
|
|
|
|
.BR _XOPEN_SOURCE
|
|
|
|
is defined.
|
|
|
|
The definition of
|
|
|
|
.BR S_IFSOCK
|
|
|
|
can also be exposed by defining
|
|
|
|
.BR _XOPEN_SOURCE
|
|
|
|
with a value of 500 or greater.
|
|
|
|
|
|
|
|
The definition of
|
|
|
|
.BR S_ISSOCK ()
|
|
|
|
is exposed if any of the following feature test macros is defined:
|
|
|
|
.BR _BSD_SOURCE
|
|
|
|
(in glibc 2.19 and earlier),
|
|
|
|
.BR _DEFAULT_SOURCE
|
|
|
|
(in glibc 2.20 and later),
|
|
|
|
.BR _XOPEN_SOURCE
|
|
|
|
with a value of 500 or greater, or
|
|
|
|
.BR _POSIX_C_SOURCE
|
|
|
|
with a value of 200112L or greater.
|
|
|
|
.PP
|
|
|
|
The following mask values are defined for
|
|
|
|
the file mode component of the
|
|
|
|
.I stx_mode
|
|
|
|
field:
|
|
|
|
.in +4n
|
|
|
|
.TS
|
|
|
|
lB l l.
|
|
|
|
S_ISUID 04000 set-user-ID bit
|
|
|
|
S_ISGID 02000 set-group-ID bit (see below)
|
|
|
|
S_ISVTX 01000 sticky bit (see below)
|
|
|
|
|
|
|
|
S_IRWXU 00700 owner has read, write, and execute permission
|
|
|
|
S_IRUSR 00400 owner has read permission
|
|
|
|
S_IWUSR 00200 owner has write permission
|
|
|
|
S_IXUSR 00100 owner has execute permission
|
|
|
|
|
|
|
|
S_IRWXG 00070 group has read, write, and execute permission
|
|
|
|
S_IRGRP 00040 group has read permission
|
|
|
|
S_IWGRP 00020 group has write permission
|
|
|
|
S_IXGRP 00010 group has execute permission
|
|
|
|
|
|
|
|
S_IRWXO 00007 T{
|
|
|
|
others (not in group) have read, write, and execute permission
|
|
|
|
T}
|
|
|
|
S_IROTH 00004 others have read permission
|
|
|
|
S_IWOTH 00002 others have write permission
|
|
|
|
S_IXOTH 00001 others have execute permission
|
|
|
|
.TE
|
|
|
|
.in
|
|
|
|
.P
|
|
|
|
The set-group-ID bit
|
|
|
|
.RB ( S_ISGID )
|
|
|
|
has several special uses.
|
|
|
|
For a directory, it indicates that BSD semantics is to be used
|
|
|
|
for that directory: files created there inherit their group ID from
|
|
|
|
the directory, not from the effective group ID of the creating process,
|
|
|
|
and directories created there will also get the
|
|
|
|
.B S_ISGID
|
|
|
|
bit set.
|
|
|
|
For a file that does not have the group execution bit
|
|
|
|
.RB ( S_IXGRP )
|
|
|
|
set,
|
|
|
|
the set-group-ID bit indicates mandatory file/record locking.
|
|
|
|
.P
|
|
|
|
The sticky bit
|
|
|
|
.RB ( S_ISVTX )
|
|
|
|
on a directory means that a file
|
|
|
|
in that directory can be renamed or deleted only by the owner
|
|
|
|
of the file, by the owner of the directory, and by a privileged
|
|
|
|
process.
|
|
|
|
.SH RETURN VALUE
|
|
|
|
On success, zero is returned.
|
|
|
|
On error, \-1 is returned, and
|
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EINVAL
|
|
|
|
Invalid flag specified in
|
|
|
|
.IR flags .
|
|
|
|
.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
|
|
|
|
Bad address.
|
|
|
|
.TP
|
|
|
|
.B ELOOP
|
|
|
|
Too many symbolic links encountered while traversing the path.
|
|
|
|
.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 AT_EMPTY_PATH was not specified.
|
|
|
|
.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 is not yet added to glibc.
|
|
|
|
.SH SEE ALSO
|
|
|
|
.BR ls (1),
|
|
|
|
.BR stat (1),
|
|
|
|
.BR access (2),
|
|
|
|
.BR chmod (2),
|
|
|
|
.BR chown (2),
|
|
|
|
.BR stat (2),
|
|
|
|
.BR readlink (2),
|
|
|
|
.BR utime (2),
|
|
|
|
.BR capabilities (7),
|
|
|
|
.BR symlink (7)
|