Hi Michael,
Could you take a look at the statx manpage in the attached patch?
In particular, a couple of questions:
(1) I've started off the description section by describing the statx struct.
I find that it helps to have this specified before getting on to
describing the arguments, among which is a mask of flags that describes
what fields have been filled in struct statx.
Should I move the struct definition to the synopsis section?
(2) I've enumerated some things by writing:
[*] By absolute path.
<... description ...>
[*] By cwd-relative path
<... description ...>
...
in the text. Is there a better way of doing this?
Thanks,
David
---
commit 0e08bb64dbbc106449cf6db08805f77db0681154
Author: David Howells <dhowells@xxxxxxxxxx>
Date: Tue Mar 7 08:18:24 2017 +0000
Man page for statx() syscall
diff --git a/man2/stat.2 b/man2/stat.2
index a567178..c4fd9a1 100644
--- a/man2/stat.2
+++ b/man2/stat.2
@@ -583,7 +583,7 @@ A component of
.I pathname
does not exist, or
.I pathname
-is an empty string.
+is an empty string and AT_EMPTY_PATH was not specified.
.TP
.B ENOMEM
Out of memory (i.e., kernel memory).
diff --git a/man2/statx.2 b/man2/statx.2
new file mode 100644
index 0000000..f372862
--- /dev/null
+++ b/man2/statx.2
@@ -0,0 +1,659 @@
+'\" t
+.\" Copyright (c) 2017 David Howells <dhowells@xxxxxxxxxx>
+.\"
+.\" Derived from the stat.2 manual page:
+.\" Copyright (c) 1992 Drew Eckhardt (drew@xxxxxxxxxxxxxxx), March 28, 1992
+.\" Parts Copyright (c) 1995 Nicolai Langfeldt (janl@xxxxxxxxxx), 1/1/95
+.\" and Copyright (c) 2006, 2007, 2014 Michael Kerrisk <mtk.manpages@xxxxxxxxx>
+.\"
+.\" %%%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 {
+ __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
+ struct statx_timestamp stx_atime; -- Time of last access
+ struct statx_timestamp stx_btime; -- Time of creation
+ struct statx_timestamp stx_ctime; -- Time of last status change
+ struct statx_timestamp stx_mtime; -- Time of last modification
+ __u32 stx_rdev_major; } Device number if device file
+ __u32 stx_rdev_minor; }
+ __u32 stx_dev_major; } Device number of containing file
+ __u32 stx_dev_minor; }
+};
+.fi
+.in
+.PP
+Where the timestamps are defined as:
+.PP
+.in +4n
+.nf
+struct statx_timestamp {
+ __s64 tv_sec; -- Number of seconds (UNIX time)
+ __s32 tv_nsec; -- Number of nanoseconds before or since tv_sec
+};
+.fi
+.in
+.PP
+(Note that reserved space and padding is omitted)
+.SS
+Invoking \fBstatx\fR():
+.PP
+To access a file's status, no permissions are required on the file itself, but
+in the case of
+.BR statx ()
+with a path, execute (search) permission is required on all of the directories
+in
+.I pathname
+that lead to the file.
+.PP
+.BR statx ()
+uses
+.IR pathname ", " dirfd " and " flags
+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
+is ignored. The file is looked up by name, starting from the root of the
+filesystem as seen by the calling process.
+.TP
+[*] By cwd-relative path.
+.I pathname
+points to a relative path and
+.IR dirfd " is " AT_FDCWD .
+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
+indicates a file descriptor pointing to a directory. The file is looked up by
+name, starting from the directory specified by
+.IR dirfd .
+.TP
+[*] By file descriptor.
+.IR pathname " is " NULL " and " dirfd
+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
+a directory.
+.PP
+.I flags
+can be used to influence a path-based lookup. A value for
+.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
+.BR lstat ().
+.PP
+.I flags
+can also be used to control what sort of synchronisation the kernel will do
+when querying a file on a remote filesystem. This is done by OR'ing in one of
+the following values:
+.TP
+AT_STATX_SYNC_AS_STAT
+Do whatever
+.BR stat ()
+does. This is the default and is very much filesystem specific.
+.TP
+AT_STATX_FORCE_SYNC
+Force the attributes to be synchronised with the server. This may require that
+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
+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 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
+filesystem supports. 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 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.
+.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
+The file type and mode. This is described in more detail below.
+.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
+The "preferred" blocksize for efficient filesystem I/O. (Writing to a file in
+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
+The file's creation timestamp. This is set on file creation and not changed
+subsequently.
+.TP
+.I stx_ctime
+The file's last status change timestamp. This field is changed by writing or
+by setting inode information (i.e., owner, group, link count, mode, etc.).
+.TP
+.I stx_mtime
+The file's last modification timestamp. This is changed by file modifications,
+for example, by
+.BR mknod (2),
+.BR truncate (2),
+.BR utime (2),
+and
+.BR write (2)
+(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
+.I not
+changed for changes in owner, group, hard link count, or mode.
+
+
+
+.PP
+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
+.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).
+
+.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
+be created to this file and no data can be written to it. See chattr(1).
+.TP
+STATX_ATTR_APPEND
+The file can only be opened in append mode for writing. Random access writing
+is not permitted. See chattr(1).
+.TP
+STATX_ATTR_NODUMP
+File is not a candidate for backup when a backup program such as dump(8) is
+run. See chattr(1).
+.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
+field contains the combined file type and mode. POSIX refers to the bits in
+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)
