[PATCH v2 0/9] xfsprogs: document the ioctls scrub uses

[PATCH v2 0/9] xfsprogs: document the ioctls scrub uses

[Darrick J. Wong]

Hi all,

Add documentation for all the ioctls that xfs_scrub uses, so that we
finally have some literature about how those interfaces are supposed to
work.

If you're going to start using this mess, you probably ought to just
pull from my git trees, which are linked below.

This is an extraordinary way to destroy everything.  Enjoy!
Comments and questions are, as always, welcome.

--D

xfsprogs git tree:
https://git.kernel.org/cgit/linux/kernel/git/djwong/xfsprogs-dev.git/log/?h=document-ioctls

[PATCH 1/9] libxfs: break out the GETXATTR/SETXATTR manpage

[Darrick J. Wong]

From: Darrick J. Wong <darrick.wong@oracle.com>

Break out the xfs file attribute get and set ioctls into a separate
manpage to reduce clutter in xfsctl.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
 man/man2/ioctl_xfs_fsgetxattr.2 |  219 +++++++++++++++++++++++++++++++++++++++
 man/man3/xfsctl.3               |  159 +---------------------------
 2 files changed, 227 insertions(+), 151 deletions(-)
 create mode 100644 man/man2/ioctl_xfs_fsgetxattr.2


diff --git a/man/man2/ioctl_xfs_fsgetxattr.2 b/man/man2/ioctl_xfs_fsgetxattr.2
new file mode 100644
index 00000000..17276dec
--- /dev/null
+++ b/man/man2/ioctl_xfs_fsgetxattr.2
@@ -0,0 +1,219 @@
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-FSGETXATTR 2 2019-04-16 "XFS"
+.SH NAME
+ioctl_xfs_fsgetxattr \- query information for an open file
+.SH SYNOPSIS
+.br
+.B #include <linux/fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTR, struct fsxattr *" arg );
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTRA, struct fsxattr *" arg );
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_FSSETXATTR, struct fsxattr *" arg );
+.SH DESCRIPTION
+Query or set additional attributes associated with files in various file
+systems.
+The attributes are conveyed in a structure of the form:
+.PP
+.in +4n
+.nf
+struct fsxattr {
+	__u32         fsx_xflags;
+	__u32         fsx_extsize;
+	__u32         fsx_nextents;
+	__u32         fsx_projid;
+	__u32         fsx_cowextsize;
+	unsigned char fsx_pad[8];
+};
+.fi
+.in
+.PP
+.I fsx_xflags
+are extended flags that apply to this file.
+This field can be a combination of the following:
+
+.RS 0.4i
+.TP
+.B FS_XFLAG_REALTIME
+The file is a realtime file.
+This bit can only be changed when the file is empty.
+.TP
+.B FS_XFLAG_PREALLOC
+The file has preallocated space.
+.TP
+.B FS_XFLAG_IMMUTABLE
+The file is immutable - it cannot be modified, deleted or renamed,
+no link can be created to this file and no data can be written to the
+file.
+Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
+capability can set or clear this flag.
+If this flag is set before a
+.B FS_IOC_SETXATTR
+call and would not be cleared by the call, then no other attributes can be
+changed and
+.B EPERM
+will be returned.
+.TP
+.B FS_XFLAG_APPEND
+The file is append-only - it can only be open in append mode for
+writing.
+Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
+capability can set or clear this flag.
+.TP
+.B FS_XFLAG_SYNC
+All writes to the file are synchronous.
+.TP
+.B FS_XFLAG_NOATIME
+When the file is accessed, its atime record is not modified.
+.TP
+.B FS_XFLAG_NODUMP
+The file should be skipped by backup utilities.
+.TP
+.B FS_XFLAG_RTINHERIT
+Realtime inheritance bit - new files created in the directory
+will be automatically realtime, and new directories created in
+the directory will inherit the inheritance bit.
+.TP
+.B FS_XFLAG_PROJINHERIT
+Project inheritance bit - new files and directories created in
+the directory will inherit the parents project ID.
+New directories also inherit the project inheritance bit.
+.TP
+.B FS_XFLAG_NOSYMLINKS
+Can only be set on a directory and disallows creation of
+symbolic links in that directory.
+.TP
+.B FS_XFLAG_EXTSIZE
+Extent size bit - if a basic extent size value is set on the file
+then the allocator will allocate in multiples of the set size for
+this file (see
+.B fsx_extsize
+below).
+This flag can only be set on a file if it is empty.
+.TP
+.B FS_XFLAG_EXTSZINHERIT
+Extent size inheritance bit - new files and directories created in
+the directory will inherit the parents basic extent size value (see
+.B fsx_extsize
+below).
+Can only be set on a directory.
+.TP
+.B FS_XFLAG_NODEFRAG
+No defragment file bit - the file should be skipped during a defragmentation
+operation. When applied to a directory, new files and directories created will
+inherit the no\-defrag bit.
+.TP
+.B FS_XFLAG_FILESTREAM
+Filestream allocator bit - allows a directory to reserve an allocation group
+for exclusive use by files created within that directory.
+Files being written in other directories will not use the same allocation group
+and so files within different directories will not interleave extents on disk.
+The reservation is only active while files are being created and written into
+the directory.
+.TP
+.B FS_XFLAG_DAX
+If the filesystem lives on directly accessible persistent memory, reads and
+writes to this file will go straight to the persistent memory, bypassing the
+page cache.
+A file cannot be reflinked and have the
+.BR FS_XFLAG_DAX
+set at the same time.
+That is to say that DAX files cannot share blocks.
+If this flag is set on a directory, files created within that directory will
+have this flag set.
+.TP
+.B FS_XFLAG_COWEXTSIZE
+Copy on Write Extent size bit - if a CoW extent size value is set on the file,
+the allocator will allocate extents for staging a copy on write operation
+in multiples of the set size for this file (see
+.B fsx_cowextsize
+below).
+If the CoW extent size is set on a directory, then new file and directories
+created in the directory will inherit the parent's CoW extent size value.
+.TP
+.B FS_XFLAG_HASATTR
+The file has extended attributes associated with it.
+.RE
+.PP
+.PD
+
+.PP
+.I fsx_extsize
+is the preferred extent allocation size for data blocks mapped to this file,
+in units of filesystem blocks.
+If this value is zero, the filesystem will choose a default option, which
+is currently zero.
+If
+.B XFS_IOC_FSSETXATTR
+is called with
+.B FS_XFLAG_EXTSIZE
+set in
+.I fsx_xflags
+and this field is zero, the XFLAG will be cleared instead.
+.PP
+.I fsx_nextents
+is the number of data extents in this file.
+If
+.B XFS_IOC_FSGETXATTRA
+was used, then this is the number of extended attribute extents in the file.
+.PP
+.I fsx_projid
+is the project ID of this file.
+.PP
+.I fsx_cowextsize
+is the preferred extent allocation size for copy on write operations
+targeting this file, in units of filesystem blocks.
+If this field is zero, the filesystem will choose a default option,
+which is currently 128 filesystem blocks.
+If
+.B XFS_IOC_FSSETXATTR
+is called with
+.B FS_XFLAG_COWEXTSIZE
+set in
+.I fsx_xflags
+and this field is zero, the XFLAG will be cleared instead.
+
+.PP
+.I fsx_pad
+must be zeroed.
+
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EACCESS
+Caller does not have sufficient access to change the attributes.
+.TP
+.B EFAULT
+The kernel was not able to copy into the userspace buffer.
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EINVAL
+One of the arguments was not valid.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.TP
+.B ENOMEM
+There was insufficient memory to perform the query.
+.TP
+.B EPERM
+Caller did not have permission to change the attributes.
+.SH CONFORMING TO
+This API is implemented by the ext4, xfs, btrfs, and f2fs filesystems on the
+Linux kernel.
+Not all fields may be understood by filesystems other than xfs.
+.SH SEE ALSO
+.BR ioctl (2)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index 462ccbd8..2992b5be 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -132,161 +132,17 @@ will fail with EINVAL.
 All I/O requests are kept consistent with any data brought into
 the cache with an access through a non-direct I/O file descriptor.
 
-.TP
-.B XFS_IOC_FSGETXATTR
-Get additional attributes associated with files in XFS file systems.
-The final argument points to a variable of type
-.BR "struct fsxattr" ,
-whose fields include:
-.B fsx_xflags
-(extended flag bits),
-.B fsx_extsize
-(nominal extent size in file system blocks),
-.B fsx_nextents
-(number of data extents in the file).
-A
-.B fsx_extsize
-value returned indicates that a preferred extent size was previously
-set on the file, a
-.B fsx_extsize
-of zero indicates that the defaults for that filesystem will be used.
-A
-.B fsx_cowextsize
-value returned indicates that a preferred copy on write extent size was
-previously set on the file, whereas a
-.B fsx_cowextsize
-of zero indicates that the defaults for that filesystem will be used.
-The current default for
-.B fsx_cowextsize
-is 128 blocks.
-Currently the meaningful bits for the
-.B fsx_xflags
-field are:
-.PD 0
-.RS
-.TP 1.0i
-.SM "Bit 0 (0x1) \- XFS_XFLAG_REALTIME"
-The file is a realtime file.
-.TP
-.SM "Bit 1 (0x2) \- XFS_XFLAG_PREALLOC"
-The file has preallocated space.
-.TP
-.SM "Bit 3 (0x8) \- XFS_XFLAG_IMMUTABLE"
-The file is immutable - it cannot be modified, deleted or renamed,
-no link can be created to this file and no data can be written to the
-file.
-Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
-capability can set or clear this flag.
-.TP
-.SM "Bit 4 (0x10) \- XFS_XFLAG_APPEND"
-The file is append-only - it can only be open in append mode for
-writing.
-Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
-capability can set or clear this flag.
-.TP
-.SM "Bit 5 (0x20) \- XFS_XFLAG_SYNC"
-All writes to the file are synchronous.
-.TP
-.SM "Bit 6 (0x40) \- XFS_XFLAG_NOATIME"
-When the file is accessed, its atime record is not modified.
-.TP
-.SM "Bit 7 (0x80) \- XFS_XFLAG_NODUMP"
-The file should be skipped by backup utilities.
-.TP
-.SM "Bit 8 (0x100) \- XFS_XFLAG_RTINHERIT"
-Realtime inheritance bit - new files created in the directory
-will be automatically realtime, and new directories created in
-the directory will inherit the inheritance bit.
-.TP
-.SM "Bit 9 (0x200) \- XFS_XFLAG_PROJINHERIT"
-Project inheritance bit - new files and directories created in
-the directory will inherit the parents project ID.  New
-directories also inherit the project inheritance bit.
-.TP
-.SM "Bit 10 (0x400) \- XFS_XFLAG_NOSYMLINKS"
-Can only be set on a directory and disallows creation of
-symbolic links in that directory.
-.TP
-.SM "Bit 11 (0x800) \- XFS_XFLAG_EXTSIZE"
-Extent size bit - if a basic extent size value is set on the file
-then the allocator will allocate in multiples of the set size for
-this file (see
-.B XFS_IOC_FSSETXATTR
-below).
-.TP
-.SM "Bit 12 (0x1000) \- XFS_XFLAG_EXTSZINHERIT"
-Extent size inheritance bit - new files and directories created in
-the directory will inherit the parents basic extent size value (see
-.B XFS_IOC_FSSETXATTR
-below).
-Can only be set on a directory.
-.TP
-.SM "Bit 13 (0x2000) \- XFS_XFLAG_NODEFRAG"
-No defragment file bit - the file should be skipped during a defragmentation
-operation. When applied to a directory, new files and directories created will
-inherit the no\-defrag bit.
-.TP
-.SM "Bit 14 (0x4000) \- XFS_XFLAG_FILESTREAM"
-Filestream allocator bit - allows a directory to reserve an allocation
-group for exclusive use by files created within that directory. Files
-being written in other directories will not use the same allocation
-group and so files within different directories will not interleave
-extents on disk. The reservation is only active while files are being
-created and written into the directory.
-.TP
-.SM "Bit 15 (0x8000) \- XFS_XFLAG_DAX"
-If the filesystem lives on directly accessible persistent memory, reads and
-writes to this file will go straight to the persistent memory, bypassing the
-page cache.
-A file cannot be reflinked and have the
-.BR XFS_XFLAG_DAX
-set at the same time.
-That is to say that DAX files cannot share blocks.
-.TP
-.SM "Bit 16 (0x10000) \- XFS_XFLAG_COWEXTSIZE"
-Copy on Write Extent size bit - if a CoW extent size value is set on the file,
-the allocator will allocate extents for staging a copy on write operation
-in multiples of the set size for this file (see
-.B XFS_IOC_FSSETXATTR
-below).
-If the CoW extent size is set on a directory, then new file and directories
-created in the directory will inherit the parent's CoW extent size value.
-.TP
-.SM "Bit 31 (0x80000000) \- XFS_XFLAG_HASATTR"
-The file has extended attributes associated with it.
-.RE
 .PP
-.PD
-
-.TP
-.B XFS_IOC_FSGETXATTRA
-Identical to
+.nf
 .B XFS_IOC_FSGETXATTR
-except that the
-.B fsx_nextents
-field contains the number of attribute extents in the file.
-
+.B XFS_IOC_FSGETXATTRA
+.fi
+.PD 0
 .TP
 .B XFS_IOC_FSSETXATTR
-Set additional attributes associated with files in XFS file systems.
-The final argument points to a variable of type
-.BR "struct fsxattr" ,
-but only the following fields are used in this call:
-.BR fsx_xflags ,
-.BR fsx_extsize ,
-.BR fsx_cowextsize ,
-and
-.BR fsx_projid .
-The
-.B fsx_xflags
-realtime file bit and the file's extent size may be changed only
-when the file is empty, except in the case of a directory where
-the extent size can be set at any time (this value is only used
-for regular file allocations, so should only be set on a directory
-in conjunction with the XFS_XFLAG_EXTSZINHERIT flag).
-The copy on write extent size,
-.BR fsx_cowextsize ,
-can be set at any time.
+See
+.BR ioctl_xfs_fsgetxattr (2)
+for more information.
 
 .TP
 .B XFS_IOC_GETBMAP
@@ -649,6 +505,7 @@ The remainder of these operations will not be described further
 as they are not of general use to applications.
 
 .SH SEE ALSO
+.BR ioctl_xfs_fsgetxattr (2),
 .BR fstatfs (2),
 .BR statfs (2),
 .BR xfs (5),

[PATCH 2/9] libxfs: break out the fsop geometry manpage

[Darrick J. Wong]

From: Darrick J. Wong <darrick.wong@oracle.com>

Break out the fs geometry ioctl into a separate manpage so that we can
document how it works.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
 man/man2/ioctl_xfs_fsop_geometry.2 |  214 ++++++++++++++++++++++++++++++++++++
 man/man3/xfsctl.3                  |   11 +-
 2 files changed, 221 insertions(+), 4 deletions(-)
 create mode 100644 man/man2/ioctl_xfs_fsop_geometry.2


diff --git a/man/man2/ioctl_xfs_fsop_geometry.2 b/man/man2/ioctl_xfs_fsop_geometry.2
new file mode 100644
index 00000000..4045e03b
--- /dev/null
+++ b/man/man2/ioctl_xfs_fsop_geometry.2
@@ -0,0 +1,214 @@
+.\" Copyright (c) 2019, Oracle.  All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-FSOP-GEOMETRY 2 2019-04-11 "XFS"
+.SH NAME
+ioctl_xfs_fsop_geometry \- report XFS filesystem shape
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_FSOP_GEOMETRY, struct xfs_fsop_geometry *" arg );
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_FSOP_GEOMETRY_V1, struct xfs_fsop_geometry_v1 *" arg );
+.SH DESCRIPTION
+Report the storage space parameters that influence allocation decisions in
+this XFS filesystem.
+This information is conveyed in a structure of the following form:
+.PP
+.in +4n
+.nf
+struct xfs_fsop_geom {
+	__u32         blocksize;
+	__u32         rtextsize;
+	__u32         agblocks;
+	__u32         agcount;
+	__u32         logblocks;
+	__u32         sectsize;
+	__u32         inodesize;
+	__u32         imaxpct;
+	__u64         datablocks;
+	__u64         rtblocks;
+	__u64         rtextents;
+	__u64         logstart;
+	unsigned char uuid[16];
+	__u32         sunit;
+	__u32         swidth;
+	__s32         version;
+	__u32         flags;
+	__u32         logsectsize;
+	__u32         rtsectsize;
+	__u32         dirblocksize;
+	/* struct xfs_fsop_geom_v1 stops here. */
+
+	__u32         logsunit;
+};
+.fi
+.in
+.PP
+.I blocksize
+is the size of a fundamental filesystem block, in bytes.
+.PP
+.I rtextsize
+is the size of an extent on the realtime volume, in bytes.
+.PP
+.I agblocks
+is the size of an allocation group, in units of filesystem blocks.
+.PP
+.I agcount
+is the number of allocation groups in the filesystem.
+.PP
+.I logblocks
+is the size of the log, in units of filesystem blocks.
+.PP
+.I sectsize
+is the smallest amount of data that can be written to the data device
+atomically, in bytes.
+.PP
+.I inodesize
+is the size of an inode record, in bytes.
+.PP
+.I imaxpct
+is the maximum percentage of the filesystem that can be allocated to inode
+record blocks.
+.PP
+.I datablocks
+is the size of the data device, in units of filesystem blocks.
+.PP
+.I rtblocks
+is the size of the realtime device, in units of filesystem blocks.
+.PP
+.I rtextents
+is the number of extents that can be allocated on the realtime device.
+This ought to be
+.RB "( " rtblocks " * " blocksize " ) / " rtextsize .
+.PP
+.I logstart
+tells the start of the log, in units of filesystem blocks.
+If the filesystem has an external log, this will be zero.
+.PP
+.I uuid
+is the universal unique identifier of the filesystem.
+.PP
+.I sunit
+is what the filesystem has been told is the size of a RAID stripe unit on the
+underlying data device, in filesystem blocks.
+.PP
+.I swidth
+is what the filesystem has been told is the width of a RAID stripe on the
+underlying data device, in units of RAID stripe units.
+.PP
+.I version
+is the version of this structure.
+This value will be XFS_FSOP_GEOM_VERSION.
+.PP
+.I flags
+tell us what features are enabled on the filesystem.
+This field can be any combination of the following:
+.RS 0.4i
+.TP
+.B XFS_FSOP_GEOM_FLAGS_ATTR
+Extended attributes are present.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_NLINK
+This filesystem supports up to 2^32 links.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_QUOTA
+Quotas are enabled.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_IALIGN
+Inodes are aligned for better performance.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_DALIGN
+Data blocks are aligned for better performance.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_SHARED
+Unused.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_EXTFLG
+Filesystem supports unwritten extents.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_DIRV2
+Directories maintain free space data for better performance.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_LOGV2
+Log uses the V2 format.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_SECTOR
+The log device has a sector size larger than 512 bytes.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_ATTR2
+Filesystem contains V2 extended attributes.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_PROJID32
+Project IDs can be as large as 2^32.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_DIRV2CI
+Case-insensitive lookups are supported on directories.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_LAZYSB
+On-disk superblock counters are updated only at unmount time.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_V5SB
+Metadata blocks are self describing and contain checksums.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_FTYPE
+Directories cache inode types in directory entries.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_FINOBT
+Filesystem maintains an index of free inodes.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_SPINODES
+Filesystem tries harder to allocate inodes when free space is fragmented.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_RMAPBT
+Filesystem stores reverse mappings of blocks to owners.
+.TP
+.B XFS_FSOP_GEOM_FLAGS_REFLINK
+Filesystem supports sharing blocks.
+.RE
+
+.PD 1
+.PP
+.I logsectsize
+is the smallest amount of data that can be written to the log device atomically,
+in bytes.
+.PP
+.I rtsectsize
+is the smallest amount of data that can be written to the realtime device
+atomically, in bytes.
+.PP
+.I dirblocksize
+is the size of directory blocks, in bytes.
+.PP
+.I logsunit
+is what the filesystem has been told is the size of a RAID stripe unit on the
+underlying log device, in filesystem blocks.
+This field is meaningful only if the flag
+.B  XFS_FSOP_GEOM_FLAGS_LOGV2
+is set.
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EFAULT
+The kernel was not able to copy into the userspace buffer.
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.SH CONFORMING TO
+This API is specific to XFS filesystem on the Linux kernel.
+.SH SEE ALSO
+.BR ioctl (2)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index 2992b5be..1237eac6 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -479,6 +479,12 @@ the kernel, except no output count parameter is used (should
 be initialized to zero).
 An error is returned if the inode number is invalid.
 
+.TP
+.B XFS_IOC_FSGEOMETRY
+See
+.BR ioctl_xfs_fsop_geometry (2)
+for more information.
+
 .PP
 .nf
 .B XFS_IOC_THAW
@@ -494,10 +500,6 @@ An error is returned if the inode number is invalid.
 These interfaces are used to implement various filesystem internal
 operations on XFS filesystems.
 For
-.B XFS_IOC_FSGEOMETRY
-(get filesystem mkfs time information), the output structure is of type
-.BR struct xfs_fsop_geom .
-For
 .B XFS_FS_COUNTS
 (get filesystem dynamic global information), the output structure is of type
 .BR xfs_fsop_counts_t .
@@ -506,6 +508,7 @@ as they are not of general use to applications.
 
 .SH SEE ALSO
 .BR ioctl_xfs_fsgetxattr (2),
+.BR ioctl_xfs_fsop_geometry (2),
 .BR fstatfs (2),
 .BR statfs (2),
 .BR xfs (5),

[PATCH 3/9] libxfs: break out the bulkstat manpage

[Darrick J. Wong]

From: Darrick J. Wong <darrick.wong@oracle.com>

Break out the bulkstat ioctl into a separate manpage so that we can
document how it works.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
 man/man2/ioctl_xfs_fsbulkstat.2 |  212 +++++++++++++++++++++++++++++++++++++++
 man/man3/xfsctl.3               |   87 +---------------
 2 files changed, 219 insertions(+), 80 deletions(-)
 create mode 100644 man/man2/ioctl_xfs_fsbulkstat.2


diff --git a/man/man2/ioctl_xfs_fsbulkstat.2 b/man/man2/ioctl_xfs_fsbulkstat.2
new file mode 100644
index 00000000..8908631a
--- /dev/null
+++ b/man/man2/ioctl_xfs_fsbulkstat.2
@@ -0,0 +1,212 @@
+.\" Copyright (c) 2019, Oracle.  All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-FSBULKSTAT 2 2019-04-11 "XFS"
+.SH NAME
+ioctl_xfs_fsbulkstat \- query information for a batch of XFS inodes
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_FSBULKSTAT, struct xfs_fsop_bulkreq *" arg );
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_FSBULKSTAT_SINGLE, struct xfs_fsop_bulkreq *" arg );
+.SH DESCRIPTION
+Query stat information for a bunch of XFS inodes.
+These ioctls use
+.B struct xfs_fsop_bulkreq
+to set up a bulk transfer with the kernel:
+.PP
+.in +4n
+.nf
+struct xfs_fsop_bulkreq {
+	__u64             *lastip;
+	__s32             count;
+	void              *ubuffer;
+	__s32             *ocount;
+};
+.fi
+.in
+.PP
+.I lastip
+points to a value that will receive the number of the "last inode".
+For
+.BR FSBULKSTAT ,
+this should be set to one less than the number of the first inode for which the
+caller wants information, or zero to start with the first inode in the
+filesystem.
+For
+.BR FSBULKSTAT_SINGLE ,
+this should be set to the number of the inode for which the caller wants
+information.
+After the call, this value will be set to the number of the last inode for
+which information was supplied.
+This field will not be updated if
+.I ocount
+is NULL.
+.PP
+.I count
+is the number of inodes to examine.
+This value must be set to 1 for
+.BR FSBULKSTAT_SINGLE .
+.PP
+.I ocount
+points to a value that will receive the number of records returned.
+If this value is NULL, then neither
+.I ocount
+nor
+.I lastip
+will be updated.
+.PP
+.I ubuffer
+points to a memory buffer where information will be copied.
+This buffer must be an array of
+.B struct xfs_bstat
+which is described below.
+The array must have at least
+.I count
+elements.
+.PP
+.in +4n
+.nf
+struct xfs_bstat {
+	__u64             bs_ino;
+	__u16             bs_mode;
+	__u16             bs_nlink;
+	__u32             bs_uid;
+	__u32             bs_gid;
+	__u32             bs_rdev;
+	__s32             bs_blksize;
+	__s64             bs_size;
+	struct xfs_bstime bs_atime;
+	struct xfs_bstime bs_mtime;
+	struct xfs_bstime bs_ctime;
+	int64_t           bs_blocks;
+	__u32             bs_xflags;
+	__s32             bs_extsize;
+	__s32             bs_extents;
+	__u32             bs_gen;
+	__u16             bs_projid_lo;
+	__u16             bs_forkoff;
+	__u16             bs_projid_hi;
+	unsigned char     bs_pad[6];
+	__u32             bs_cowextsize;
+	__u32             bs_dmevmask;
+	__u16             bs_dmstate;
+	__u16             bs_aextents;
+};
+.fi
+.in
+.PP
+.I bs_ino
+is the number of this inode record.
+.PP
+.I bs_mode
+is the file type and mode.
+.PP
+.I bs_nlink
+is the number of hard links to this inode.
+.PP
+.I bs_uid
+is the user id.
+.PP
+.I bs_gid
+is the group id.
+.PP
+.I bs_rdev
+is the encoded device id if this is a special file.
+.PP
+.I bs_blksize
+is the size of a data block for this file, in units of bytes.
+.PP
+.I bs_size
+is the size of the file, in bytes.
+.PP
+.I bs_atime
+is the last time this file was accessed.
+.PP
+.I bs_mtime
+is the last time the contents of this file were modified.
+.PP
+.I bs_ctime
+is the last time this inode record was modified.
+.PP
+.I bs_blocks
+is the number of filesystem blocks allocated to this file, including metadata.
+.PP
+.I bs_xflags
+tell us what extended flags are set this inode.
+These flags are the same values as those set in the
+.I fsx_xflags
+field of
+.BR "struct fsxattr" ;
+please see the
+.BR ioctl_fsgetxattr (2)
+manpage for more information.
+
+.PD 1
+.PP
+.I bs_extsize
+is the extent size hint for this file, in bytes.
+.PP
+.I bs_extents
+is the number of storage space extents associated with this file's data.
+.PP
+.I bs_gen
+is the generation number of the inode record.
+.PP
+.I bs_projid_lo
+is the lower 16-bits of the project id.
+.PP
+.I bs_forkoff
+is the offset of the attribute fork in the inode record, in bytes.
+.PP
+.I bs_projid_hi
+is the upper 16-bits of the project id.
+.PP
+.I bs_pad[6]
+is zeroed.
+.PP
+.I bs_cowextsize
+is the Copy on Write extent size hint for this file, in bytes.
+.PP
+.I bs_dmevmask
+is unused on Linux.
+.PP
+.I bs_dmstate
+is unused on Linux.
+.PP
+.I bs_aextents
+is the number of storage space extents associated with this file's extended
+attributes.
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EFAULT
+The kernel was not able to copy into the userspace buffer.
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EINVAL
+One of the arguments was not valid.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.TP
+.B ENOMEM
+There was insufficient memory to perform the query.
+.SH CONFORMING TO
+This API is specific to XFS filesystem on the Linux kernel.
+.SH SEE ALSO
+.BR ioctl (2)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index 1237eac6..94a6ad4b 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -399,92 +399,18 @@ An output
 .B ocount
 value of zero means that the inode table has been exhausted.
 
-.TP
-.B XFS_IOC_FSBULKSTAT
-This interface is used to extract inode information (stat
-information) "in bulk" from a filesystem.  It is intended to
-be called iteratively, to obtain information about the entire
-set of inodes in a filesystem.
-The information is passed in and out via a structure of type
-.B xfs_fsop_bulkreq_t
-pointed to by the final argument.
-.B lastip
-is a pointer to a variable containing the last inode number returned,
-initially it should be zero.
-.B icount
-indicates the size of the array of structures specified by
-.B ubuffer.
-.B ubuffer
-is the address of an array of structures of type
-.BR xfs_bstat_t .
-Many of the elements in the structure are the same as for the stat
-structure.
-The structure has the following elements:
-.B bs_ino
-(inode number),
-.B bs_mode
-(type and mode),
-.B bs_nlink
-(number of links),
-.B bs_uid
-(user id),
-.B bs_gid
-(group id),
-.B bs_rdev
-(device value),
-.B bs_blksize
-(block size of the filesystem),
-.B bs_size
-(file size in bytes),
-.B bs_atime
-(access time),
-.B bs_mtime
-(modify time),
-.B bs_ctime
-(inode change time),
-.B bs_blocks
-(number of blocks used by the file),
-.B bs_xflags
-(extended flags),
-.B bs_extsize
-(extent size),
-.B bs_extents
-(number of extents),
-.B bs_gen
-(generation count),
-.B bs_projid_lo
-(project id - low word),
-.B bs_projid_hi
-(project id - high word, used when projid32bit feature is enabled),
-.B bs_dmevmask
-(DMIG event mask),
-.B bs_dmstate
-(DMIG state information), and
-.B bs_aextents
-(attribute extent count).
-.B ocount
-is a pointer to a count of returned values, filled in by the call.
-An output
-.B ocount
-value of zero means that the inode table has been exhausted.
-
-.TP
-.B XFS_IOC_FSBULKSTAT_SINGLE
-This interface is a variant of the
-.B XFS_IOC_FSBULKSTAT
-interface, used to obtain information about a single inode.
-for an open file in the filesystem of interest.
-The same structure is used to pass information in and out of
-the kernel, except no output count parameter is used (should
-be initialized to zero).
-An error is returned if the inode number is invalid.
-
 .TP
 .B XFS_IOC_FSGEOMETRY
 See
 .BR ioctl_xfs_fsop_geometry (2)
 for more information.
 
+.TP
+.BR XFS_IOC_FSBULKSTAT " or " XFS_IOC_FSBULKSTAT_SINGLE
+See
+.BR ioctl_xfs_fsbulkstat (2)
+for more information.
+
 .PP
 .nf
 .B XFS_IOC_THAW
@@ -509,6 +435,7 @@ as they are not of general use to applications.
 .SH SEE ALSO
 .BR ioctl_xfs_fsgetxattr (2),
 .BR ioctl_xfs_fsop_geometry (2),
+.BR ioctl_xfs_fsbulkstat (2),
 .BR fstatfs (2),
 .BR statfs (2),
 .BR xfs (5),

[PATCH 4/9] libxfs: link to the scrub ioctl from xfsctl.3

[Darrick J. Wong]

From: Darrick J. Wong <darrick.wong@oracle.com>

Link to the scrub ioctl documentation from xfsctl.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
 man/man3/xfsctl.3 |    6 ++++++
 1 file changed, 6 insertions(+)


diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index 94a6ad4b..cdf0fcfc 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -411,6 +411,12 @@ See
 .BR ioctl_xfs_fsbulkstat (2)
 for more information.
 
+.TP
+.B XFS_IOC_SCRUB_METADATA
+See
+.BR ioctl_xfs_scrub_metadata (2)
+for more information.
+
 .PP
 .nf
 .B XFS_IOC_THAW

[PATCH 5/9] libxfs: break out the INUMBERS manpage

[Darrick J. Wong]

From: Darrick J. Wong <darrick.wong@oracle.com>

Create a separate manual page for the INUMBERS ioctl so we can document
how it works.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
 man/man2/ioctl_xfs_fsinumbers.2 |  115 +++++++++++++++++++++++++++++++++++++++
 man/man3/xfsctl.3               |   34 +-----------
 2 files changed, 119 insertions(+), 30 deletions(-)
 create mode 100644 man/man2/ioctl_xfs_fsinumbers.2


diff --git a/man/man2/ioctl_xfs_fsinumbers.2 b/man/man2/ioctl_xfs_fsinumbers.2
new file mode 100644
index 00000000..86cdf4d9
--- /dev/null
+++ b/man/man2/ioctl_xfs_fsinumbers.2
@@ -0,0 +1,115 @@
+.\" Copyright (c) 2019, Oracle.  All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-FSINUMBERS 2 2019-04-16 "XFS"
+.SH NAME
+ioctl_xfs_fsinumbers \- extract a list of valid inode numbers from an XFS filesystem
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_FSINUMBERS, struct xfs_fsop_bulkreq *" arg );
+.SH DESCRIPTION
+Query a list of valid inode numbers from an XFS filesystem.
+It is intended to be called iteratively to obtain the entire set of inodes.
+These ioctls use
+.B struct xfs_fsop_bulkreq
+to set up a bulk transfer with the kernel:
+.PP
+.in +4n
+.nf
+struct xfs_fsop_bulkreq {
+	__u64   *lastip;
+	__s32   count;
+	void    *ubuffer;
+	__s32   *ocount;
+};
+.fi
+.in
+.PP
+.I lastip
+points to a value that will receive the number of the "last inode".
+This should be set to one less than the number of the first inode for which the
+caller wants information, or zero to start with the first inode in the
+filesystem.
+After the call, this value will be set to the number of the last inode for
+which information is supplied.
+This field will not be updated if
+.I ocount
+is NULL.
+.PP
+.I count
+is the number of inodes to examine.
+.PP
+.I ocount
+points to a value that will receive the number of records returned.
+An output value of zero means that there are no more inodes left to enumerate.
+If this value is NULL, then neither
+.I ocount
+nor
+.I lastip
+will be updated.
+.PP
+.I ubuffer
+points to a memory buffer where information will be copied.
+This buffer must be an array of
+.B struct xfs_inogrp
+which is described below.
+The array must have at least
+.I count
+elements.
+.PP
+.in +4n
+.nf
+struct xfs_inogrp {
+	__u64   xi_startino;
+	__s32   xi_alloccount;
+	__u64   xi_allocmask;
+}
+.fi
+.in
+.PP
+.I xi_startino
+is the number of this inode numbers record.
+Each inode numbers record will correspond roughly to a record in the inode
+btree, though this is not guaranteed.
+.PP
+.I xi_alloccount
+is the number of bits that are set in
+.IR xi_allocmask .
+.PP
+.I xi_allocmask
+is the mask of inodes that are in use for this inode.
+The bitmask is 64 bits long, and the least significant bit corresponds to inode
+.BR xi_startino .
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EFAULT
+The kernel was not able to copy into the userspace buffer.
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EINVAL
+One of the arguments was not valid.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.TP
+.B ENOMEM
+There was insufficient memory to perform the query.
+.SH CONFORMING TO
+This API is specific to XFS filesystem on the Linux kernel.
+.SH SEE ALSO
+.BR ioctl (2)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index cdf0fcfc..148119a9 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -368,36 +368,9 @@ can be any open file in the XFS filesystem in question.
 .PP
 .TP
 .B XFS_IOC_FSINUMBERS
-This interface is used to extract a list of valid inode numbers from an
-XFS filesystem.
-It is intended to be called iteratively, to obtain the entire set of inodes.
-The information is passed in and out via a structure of type
-.B xfs_fsop_bulkreq_t
-pointed to by the final argument.
-.B lastip
-is a pointer to a variable containing the last inode number returned,
-initially it should be zero.
-.B icount
-is the size of the array of structures specified by
-.BR ubuffer .
-.B ubuffer
-is the address of an array of structures, of type
-.BR xfs_inogrp_t .
-This structure has the following elements:
-.B xi_startino
-(starting inode number),
-.B xi_alloccount
-(count of bits set in xi_allocmask), and
-.B xi_allocmask
-(mask of allocated inodes in this group).
-The bitmask is 64 bits long, and the least significant bit corresponds to inode
-.B xi_startino.
-Each bit is set if the corresponding inode is in use.
-.B ocount
-is a pointer to a count of returned values, filled in by the call.
-An output
-.B ocount
-value of zero means that the inode table has been exhausted.
+See
+.BR ioctl_xfs_fsinumbers (2)
+for more information.
 
 .TP
 .B XFS_IOC_FSGEOMETRY
@@ -442,6 +415,7 @@ as they are not of general use to applications.
 .BR ioctl_xfs_fsgetxattr (2),
 .BR ioctl_xfs_fsop_geometry (2),
 .BR ioctl_xfs_fsbulkstat (2),
+.BR ioctl_xfs_fsinumbers (2),
 .BR fstatfs (2),
 .BR statfs (2),
 .BR xfs (5),

[PATCH 6/9] libxfs: break out FSCOUNTS manpage

[Darrick J. Wong]

From: Darrick J. Wong <darrick.wong@oracle.com>

Create a separate manual page for the FSCOUNTS ioctl so we can document
how it works.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
 man/man2/ioctl_xfs_fscounts.2 |   67 +++++++++++++++++++++++++++++++++++++++++
 man/man3/xfsctl.3             |   14 +++++----
 2 files changed, 75 insertions(+), 6 deletions(-)
 create mode 100644 man/man2/ioctl_xfs_fscounts.2


diff --git a/man/man2/ioctl_xfs_fscounts.2 b/man/man2/ioctl_xfs_fscounts.2
new file mode 100644
index 00000000..44b214a1
--- /dev/null
+++ b/man/man2/ioctl_xfs_fscounts.2
@@ -0,0 +1,67 @@
+.\" Copyright (c) 2019, Oracle.  All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-FSCOUNTS 2 2019-04-16 "XFS"
+.SH NAME
+ioctl_xfs_fscounts \- query XFS summary counter information
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_FSCOUNTS, struct xfs_fsop_counts *" arg );
+.SH DESCRIPTION
+Query the raw filesystem summary counters.
+Unlike
+.BR statvfs (3),
+the values returned here are the raw values, which do not reflect any
+alterations or limits set by quotas.
+The counter information is conveyed in a structure of the following form:
+.PP
+.in +4n
+.nf
+struct xfs_fscounts {
+	__u64   freedata;
+	__u64   freertx;
+	__u64   freeino;
+	__u64   allocino;
+};
+.fi
+.in
+.PP
+.I freedata
+is the number of free filesystem blocks on the data device.
+.PP
+.I freertx
+is the number of free xtents on the realtime device.
+.PP
+.I freeino
+is the number of inode records that are not in use within the space that has
+been allocated for them.
+.PP
+.I allocino
+is the number of inode records for which space has been allocated.
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EINVAL
+The specified allocation group number is not valid for this filesystem.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.SH CONFORMING TO
+This API is specific to XFS filesystem on the Linux kernel.
+.SH SEE ALSO
+.BR ioctl (2)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index 148119a9..007f7d58 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -390,6 +390,12 @@ See
 .BR ioctl_xfs_scrub_metadata (2)
 for more information.
 
+.TP
+.B XFS_IOC_FSCOUNTS
+See
+.BR ioctl_xfs_fscounts (2)
+for more information.
+
 .PP
 .nf
 .B XFS_IOC_THAW
@@ -398,16 +404,11 @@ for more information.
 .B XFS_IOC_SET_RESBLKS
 .B XFS_IOC_FSGROWFSDATA
 .B XFS_IOC_FSGROWFSLOG
-.B XFS_IOC_FSGROWFSRT
 .fi
 .TP
-.B XFS_IOC_FSCOUNTS
+.B XFS_IOC_FSGROWFSRT
 These interfaces are used to implement various filesystem internal
 operations on XFS filesystems.
-For
-.B XFS_FS_COUNTS
-(get filesystem dynamic global information), the output structure is of type
-.BR xfs_fsop_counts_t .
 The remainder of these operations will not be described further
 as they are not of general use to applications.
 
@@ -416,6 +417,7 @@ as they are not of general use to applications.
 .BR ioctl_xfs_fsop_geometry (2),
 .BR ioctl_xfs_fsbulkstat (2),
 .BR ioctl_xfs_fsinumbers (2),
+.BR ioctl_xfs_fscounts (2),
 .BR fstatfs (2),
 .BR statfs (2),
 .BR xfs (5),

[PATCH 7/9] libxfs: break out the RESBLKS manpage

[Darrick J. Wong]

From: Darrick J. Wong <darrick.wong@oracle.com>

Create a separate manual page for the RESBLKS ioctls so we can document
how they work.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
 man/man2/ioctl_xfs_getresblks.2 |   65 +++++++++++++++++++++++++++++++++++++++
 man/man3/xfsctl.3               |   14 +++++++-
 2 files changed, 77 insertions(+), 2 deletions(-)
 create mode 100644 man/man2/ioctl_xfs_getresblks.2


diff --git a/man/man2/ioctl_xfs_getresblks.2 b/man/man2/ioctl_xfs_getresblks.2
new file mode 100644
index 00000000..57533927
--- /dev/null
+++ b/man/man2/ioctl_xfs_getresblks.2
@@ -0,0 +1,65 @@
+.\" Copyright (c) 2019, Oracle.  All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-GETRESBLKS 2 2019-04-16 "XFS"
+.SH NAME
+ioctl_xfs_getresblks \- query XFS summary counter information
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_GET_RESBLKS, struct xfs_fsop_resblks *" arg );
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_SET_RESBLKS, struct xfs_fsop_resblks *" arg );
+.SH DESCRIPTION
+Query or set the free space reservation information.
+These blocks are reserved by the filesystem as a last-ditch attempt to prevent
+metadata update failures due to insufficient space.
+Only the system administrator can call these ioctls, because overriding the
+defaults is extremely dangerous and should never be tried by anyone.
+.PP
+The reservation information is conveyed in a structure of the following form:
+.PP
+.in +4n
+.nf
+struct xfs_fsop_resblks {
+	__u64  resblks;
+	__u64  resblks_avail;
+};
+.fi
+.in
+.PP
+.I resblks
+is the number of blocks that the filesystem will try to maintain to prevent
+critical out of space situations.
+.PP
+.I resblks_avail
+is the number of reserved blocks remaining.
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EINVAL
+The specified allocation group number is not valid for this filesystem.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.TP
+.B EPERM
+Caller does not have permission to call this ioctl.
+.SH CONFORMING TO
+This API is specific to XFS filesystem on the Linux kernel.
+.SH SEE ALSO
+.BR ioctl (2)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index 007f7d58..25e51417 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -396,12 +396,21 @@ See
 .BR ioctl_xfs_fscounts (2)
 for more information.
 
+.TP
+.nf
+.B XFS_IOC_GET_RESBLKS
+.fi
+.TP
+.B XFS_IOC_SET_RESBLKS
+See
+.BR ioctl_xfs_getresblks (2)
+for more information.
+Save yourself a lot of frustration and avoid these ioctls.
+
 .PP
 .nf
 .B XFS_IOC_THAW
 .B XFS_IOC_FREEZE
-.B XFS_IOC_GET_RESBLKS
-.B XFS_IOC_SET_RESBLKS
 .B XFS_IOC_FSGROWFSDATA
 .B XFS_IOC_FSGROWFSLOG
 .fi
@@ -418,6 +427,7 @@ as they are not of general use to applications.
 .BR ioctl_xfs_fsbulkstat (2),
 .BR ioctl_xfs_fsinumbers (2),
 .BR ioctl_xfs_fscounts (2),
+.BR ioctl_xfs_getresblks (2),
 .BR fstatfs (2),
 .BR statfs (2),
 .BR xfs (5),

[PATCH 8/9] libxfs: break out GETBMAP manpage

[Darrick J. Wong]

From: Darrick J. Wong <darrick.wong@oracle.com>

Create a separate manual page for the BMAP ioctls so we can document how
they work.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
 man/man2/ioctl_xfs_getbmap.2 |  165 ++++++++++++++++++++++++++++++++++++++++++
 man/man3/xfsctl.3            |   61 +++-------------
 2 files changed, 175 insertions(+), 51 deletions(-)
 create mode 100644 man/man2/ioctl_xfs_getbmap.2


diff --git a/man/man2/ioctl_xfs_getbmap.2 b/man/man2/ioctl_xfs_getbmap.2
new file mode 100644
index 00000000..5097173b
--- /dev/null
+++ b/man/man2/ioctl_xfs_getbmap.2
@@ -0,0 +1,165 @@
+.\" Copyright (c) 2019, Oracle.  All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-GETBMAP 2 2019-04-11 "XFS"
+.SH NAME
+ioctl_xfs_getbmap \- query extent information for an open file
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_GETBMAP, struct getbmap *" arg );
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_GETBMAPA, struct getbmap *" arg );
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_GETBMAPX, struct getbmapx *" arg );
+.SH DESCRIPTION
+Get the block map for a segment of a file in an XFS file system.
+The mapping information is conveyed in a structure of the following form:
+.PP
+.in +4n
+.nf
+struct getbmap {
+	__s64   bmv_offset;
+	__s64   bmv_block;
+	__s64   bmv_length;
+	__s32   bmv_count;
+	__s32   bmv_entries;
+};
+.fi
+.in
+.PP
+The
+.B XFS_IOC_GETBMAPX
+ioctl uses a larger version of that structure:
+.PP
+.in +4n
+.nf
+struct getbmapx {
+	__s64   bmv_offset;
+	__s64   bmv_block;
+	__s64   bmv_length;
+	__s32   bmv_count;
+	__s32   bmv_entries;
+	__s32   bmv_iflags;
+	__s32   bmv_oflags;
+	__s32   bmv_unused1;
+	__s32   bmv_unused2;
+};
+.fi
+.in
+.PP
+All sizes and offsets in the structure are in units of 512 bytes.
+.PP
+The first structure in the array is a header and the remaining structures in
+the array contain block map information on return.
+The header controls iterative calls to the command and should be filled out as
+follows:
+.TP
+.B bmv_offset
+The file offset of the area of interest in the file.
+.TP
+.B bmv_length
+The length of the area of interest in the file.
+If this value is set to -1, the length of the interesting area is the rest of
+the file.
+.TP
+.B bmv_count
+The length of the array, including this header.
+.TP
+.B bmv_entries
+The number of entries actually filled in by the call.
+This does not need to be filled out before the call.
+.TP
+.B bmv_iflags
+For the
+.B XFS_IOC_GETBMAPX
+function, this is a combination of the following flags:
+.RS 0.4i
+.TP
+.B BMV_IF_ATTRFORK
+Return information about the extended attribute fork.
+.TP
+.B BMV_IF_PREALLOC
+Return information about unwritten pre-allocated segments.
+.TP
+.B BMV_IF_DELALLOC
+Return information about delayed allocation reservation segments.
+.TP
+.B BMV_IF_NO_HOLES
+Do not return information about holes.
+.RE
+.PD 1
+
+.PP
+On return from a call, the header is updated so that the command can be
+reused to obtain more information without re-initializing the structures.
+The remainder of the array will be filled out by the call as follows:
+
+.TP
+.B bmv_offset
+File offset of segment.
+.TP
+.B bmv_block
+Physical starting block of segment.
+If this is -1, then the segment is a hole.
+.TP
+.B bmv_length
+Length of segment.
+.TP
+.B bmv_oflags
+The
+.B XFS_IOC_GETBMAPX
+function will fill this field with a combination of the following flags:
+.RS 0.4i
+.TP
+.B BMV_OF_PREALLOC
+The segment is an unwritten pre-allocation.
+.TP
+.B BMV_OF_DELALLOC
+The segment is a delayed allocation reservation.
+.TP
+.B BMV_OF_LAST
+This segment is the last in the file.
+.TP
+.B BMV_OF_SHARED
+This segment shares blocks with other files.
+.RE
+.PD 1
+.PP
+The
+.B XFS_IOC_GETBMAPA
+command is identical to
+.B XFS_IOC_GETBMAP
+except that information about the attribute fork of the file is returned.
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EFAULT
+The kernel was not able to copy into the userspace buffer.
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EINVAL
+One of the arguments was not valid.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.TP
+.B ENOMEM
+There was insufficient memory to perform the query.
+.SH CONFORMING TO
+This API is specific to XFS filesystem on the Linux kernel.
+.SH SEE ALSO
+.BR ioctl (2)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index 25e51417..e0986afb 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -144,59 +144,17 @@ See
 .BR ioctl_xfs_fsgetxattr (2)
 for more information.
 
-.TP
-.B XFS_IOC_GETBMAP
-Get the block map for a segment of a file in an XFS file system.
-The final argument points to an arry of variables of type
-.BR "struct getbmap" .
-All sizes and offsets in the structure are in units of 512 bytes.
-The structure fields include:
-.B bmv_offset
-(file offset of segment),
-.B bmv_block
-(starting block of segment),
-.B bmv_length
-(length of segment),
-.B bmv_count
-(number of array entries, including the first), and
-.B bmv_entries
-(number of entries filled in).
-The first structure in the array is a header, and the remaining
-structures in the array contain block map information on return.
-The header controls iterative calls to the
+.PP
+.nf
 .B XFS_IOC_GETBMAP
-command.
-The caller fills in the
-.B bmv_offset
-and
-.B bmv_length
-fields of the header to indicate the area of interest in the file,
-and fills in the
-.B bmv_count
-field to indicate the length of the array.
-If the
-.B bmv_length
-value is set to \-1 then the length of the interesting area is the rest
-of the file.
-On return from a call, the header is updated so that the command can be
-reused to obtain more information, without re-initializing the structures.
-Also on return, the
-.B bmv_entries
-field of the header is set to the number of array entries actually filled in.
-The non-header structures will be filled in with
-.BR bmv_offset ,
-.BR bmv_block ,
-and
-.BR bmv_length .
-If a region of the file has no blocks (is a hole in the file) then the
-.B bmv_block
-field is set to \-1.
-
-.TP
 .B XFS_IOC_GETBMAPA
-Identical to
-.B XFS_IOC_GETBMAP
-except that information about the attribute fork of the file is returned.
+.fi
+.PD 0
+.TP
+.B XFS_IOC_GETBMAPX
+See
+.BR ioctl_getbmap (2)
+for more information.
 
 .PP
 .B XFS_IOC_RESVSP
@@ -428,6 +386,7 @@ as they are not of general use to applications.
 .BR ioctl_xfs_fsinumbers (2),
 .BR ioctl_xfs_fscounts (2),
 .BR ioctl_xfs_getresblks (2),
+.BR ioctl_xfs_getbmap (2),
 .BR fstatfs (2),
 .BR statfs (2),
 .BR xfs (5),

[PATCH 9/9] libxfs: break out fs shutdown manpage

[Darrick J. Wong]

From: Darrick J. Wong <darrick.wong@oracle.com>

Create a separate manual page for the fs shutdown ioctl so we can
document how it works.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
---
 man/man2/ioctl_xfs_goingdown.2 |   61 ++++++++++++++++++++++++++++++++++++++++
 man/man3/xfsctl.3              |    7 +++++
 2 files changed, 68 insertions(+)
 create mode 100644 man/man2/ioctl_xfs_goingdown.2


diff --git a/man/man2/ioctl_xfs_goingdown.2 b/man/man2/ioctl_xfs_goingdown.2
new file mode 100644
index 00000000..e9a56f28
--- /dev/null
+++ b/man/man2/ioctl_xfs_goingdown.2
@@ -0,0 +1,61 @@
+.\" Copyright (c) 2019, Oracle.  All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-GOINGDOWN 2 2019-04-16 "XFS"
+.SH NAME
+ioctl_xfs_goingdown \- shut down an XFS filesystem
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_GOINGDOWN, uint32_t " flags );
+.SH DESCRIPTION
+Shuts down a live XFS filesystem.
+This is a software initiated hard shutdown and should be avoided whenever
+possible.
+After this call completes, the filesystem will be totally unusable and must be
+unmounted.
+
+.PP
+.I flags
+can be one of the following:
+.RS 0.4i
+.TP
+.B XFS_FSOP_GOING_FLAGS_DEFAULT
+Flush all dirty data and in-core state to disk, flush the log, then shut down.
+.TP
+.B XFS_FSOP_GOING_FLAGS_LOGFLUSH
+Flush all pending transactions to the log, then shut down, leaving all dirty
+data unwritten.
+.TP
+.B XFS_FSOP_GOING_FLAGS_NOLOGFLUSH
+Shut down, leaving all dirty transactions and dirty data.
+
+.SH RETURN VALUE
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+.PP
+.SH ERRORS
+Error codes can be one of, but are not limited to, the following:
+.TP
+.B EFSBADCRC
+Metadata checksum validation failed while performing the query.
+.TP
+.B EFSCORRUPTED
+Metadata corruption was encountered while performing the query.
+.TP
+.B EINVAL
+The specified allocation group number is not valid for this filesystem.
+.TP
+.B EIO
+An I/O error was encountered while performing the query.
+.TP
+.B EPERM
+Caller did not have permission to shut down the filesystem.
+.SH CONFORMING TO
+This API is specific to XFS filesystem on the Linux kernel.
+.SH SEE ALSO
+.BR ioctl (2)
diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
index e0986afb..ca96a007 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -365,6 +365,12 @@ See
 for more information.
 Save yourself a lot of frustration and avoid these ioctls.
 
+.TP
+.B XFS_IOC_GOINGDOWN
+See
+.BR ioctl_xfs_goingdown (2)
+for more information.
+
 .PP
 .nf
 .B XFS_IOC_THAW
@@ -387,6 +393,7 @@ as they are not of general use to applications.
 .BR ioctl_xfs_fscounts (2),
 .BR ioctl_xfs_getresblks (2),
 .BR ioctl_xfs_getbmap (2),
+.BR ioctl_xfs_goingdown (2),
 .BR fstatfs (2),
 .BR statfs (2),
 .BR xfs (5),

Re: [PATCH 1/9] libxfs: break out the GETXATTR/SETXATTR manpage

[Eric Sandeen]

On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
> 
> Break out the xfs file attribute get and set ioctls into a separate
> manpage to reduce clutter in xfsctl.

<comes up for air>

Now that we've uh, hoisted it to be a generic vfs interface,
FS_IOC_FSGETXATTR, shouldn't we be documenting it as that instead
of the (old) xfs variant?

(honestly that'd be mostly just search and replace for this patch)

Except of course XFS_IOC_FSGETXATTRA has no vfs variant.  :/

I also wonder if FS_IOC_SETFLAGS should be mentioned, and/or a
SEE_ALSO because some of the functionality overlaps?

> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
>  man/man2/ioctl_xfs_fsgetxattr.2 |  219 +++++++++++++++++++++++++++++++++++++++
>  man/man3/xfsctl.3               |  159 +---------------------------
>  2 files changed, 227 insertions(+), 151 deletions(-)
>  create mode 100644 man/man2/ioctl_xfs_fsgetxattr.2
> 
> 
> diff --git a/man/man2/ioctl_xfs_fsgetxattr.2 b/man/man2/ioctl_xfs_fsgetxattr.2
> new file mode 100644
> index 00000000..17276dec
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_fsgetxattr.2
> @@ -0,0 +1,219 @@
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-FSGETXATTR 2 2019-04-16 "XFS"
> +.SH NAME
> +ioctl_xfs_fsgetxattr \- query information for an open file
> +.SH SYNOPSIS
> +.br
> +.B #include <linux/fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTR, struct fsxattr *" arg );
> +.PP

maybe

.br

here to keep it more compact?  Unless there's a manpage style I'm unaware
of?

> +.BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTRA, struct fsxattr *" arg );
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_FSSETXATTR, struct fsxattr *" arg );
> +.SH DESCRIPTION
> +Query or set additional attributes associated with files in various file
> +systems.

(it was the "various filesystems" which caught my eye and reminded me to
ask the first question)

> +The attributes are conveyed in a structure of the form:
> +.PP
> +.in +4n
> +.nf
> +struct fsxattr {
> +	__u32         fsx_xflags;
> +	__u32         fsx_extsize;
> +	__u32         fsx_nextents;
> +	__u32         fsx_projid;
> +	__u32         fsx_cowextsize;
> +	unsigned char fsx_pad[8];
> +};
> +.fi
> +.in
> +.PP
> +.I fsx_xflags
> +are extended flags that apply to this file.
> +This field can be a combination of the following:
> +
> +.RS 0.4i
> +.TP
> +.B FS_XFLAG_REALTIME
> +The file is a realtime file.
> +This bit can only be changed when the file is empty.
> +.TP
> +.B FS_XFLAG_PREALLOC
> +The file has preallocated space.
> +.TP
> +.B FS_XFLAG_IMMUTABLE
> +The file is immutable - it cannot be modified, deleted or renamed,
> +no link can be created to this file and no data can be written to the
> +file.
> +Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
> +capability can set or clear this flag.
> +If this flag is set before a
> +.B FS_IOC_SETXATTR

(and here you do refer to the non-XFS variant)

> +call and would not be cleared by the call, then no other attributes can be
> +changed and
> +.B EPERM
> +will be returned.
> +.TP
> +.B FS_XFLAG_APPEND
> +The file is append-only - it can only be open in append mode for
> +writing.
> +Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
> +capability can set or clear this flag.
> +.TP
> +.B FS_XFLAG_SYNC
> +All writes to the file are synchronous.
> +.TP
> +.B FS_XFLAG_NOATIME
> +When the file is accessed, its atime record is not modified.
> +.TP
> +.B FS_XFLAG_NODUMP
> +The file should be skipped by backup utilities.
> +.TP
> +.B FS_XFLAG_RTINHERIT
> +Realtime inheritance bit - new files created in the directory
> +will be automatically realtime, and new directories created in
> +the directory will inherit the inheritance bit.
> +.TP
> +.B FS_XFLAG_PROJINHERIT
> +Project inheritance bit - new files and directories created in
> +the directory will inherit the parents project ID.

s/parents/parent directory's/

> +New directories also inherit the project inheritance bit.

also may as well keep the text for RTINHERIT and PROJINHERIT
identical other than the bit name/description.

> +.TP
> +.B FS_XFLAG_NOSYMLINKS
> +Can only be set on a directory and disallows creation of
> +symbolic links in that directory.
> +.TP
> +.B FS_XFLAG_EXTSIZE
> +Extent size bit - if a basic extent size value is set on the file
> +then the allocator will allocate in multiples of the set size for
> +this file (see
> +.B fsx_extsize
> +below).
> +This flag can only be set on a file if it is empty.
> +.TP
> +.B FS_XFLAG_EXTSZINHERIT
> +Extent size inheritance bit - new files and directories created in
> +the directory will inherit the parents basic extent size value (see

s/parents/parent directory's/

again probably keep text same as RTINHERIT/PROJINHERIT modulo bit name.

> +.B fsx_extsize
> +below).
> +Can only be set on a directory.

(i.e. the others "can only be set on a directory" too right?)

> +.TP
> +.B FS_XFLAG_NODEFRAG
> +No defragment file bit - the file should be skipped during a defragmentation
> +operation. When applied to a directory, new files and directories created will
> +inherit the no\-defrag bit.
> +.TP
> +.B FS_XFLAG_FILESTREAM
> +Filestream allocator bit - allows a directory to reserve an allocation group
> +for exclusive use by files created within that directory.
> +Files being written in other directories will not use the same allocation group
> +and so files within different directories will not interleave extents on disk.
> +The reservation is only active while files are being created and written into
> +the directory.
> +.TP
> +.B FS_XFLAG_DAX
> +If the filesystem lives on directly accessible persistent memory, reads and
> +writes to this file will go straight to the persistent memory, bypassing the
> +page cache.
> +A file cannot be reflinked and have the
> +.BR FS_XFLAG_DAX
> +set at the same time.

Since you can't even mount that way, I suppose not ....

> +That is to say that DAX files cannot share blocks.
> +If this flag is set on a directory, files created within that directory will
> +have this flag set.

Documenting DAX is a bold move...

Do subdirs not inherit the flag?


> +.TP
> +.B FS_XFLAG_COWEXTSIZE
> +Copy on Write Extent size bit - if a CoW extent size value is set on the file,
> +the allocator will allocate extents for staging a copy on write operation
> +in multiples of the set size for this file (see
> +.B fsx_cowextsize
> +below).
> +If the CoW extent size is set on a directory, then new file and directories
> +created in the directory will inherit the parent's CoW extent size value.
> +.TP
> +.B FS_XFLAG_HASATTR
> +The file has extended attributes associated with it.
> +.RE
> +.PP
> +.PD
> +
> +.PP
> +.I fsx_extsize
> +is the preferred extent allocation size for data blocks mapped to this file,
> +in units of filesystem blocks.
> +If this value is zero, the filesystem will choose a default option, which
> +is currently zero.
> +If
> +.B XFS_IOC_FSSETXATTR
> +is called with
> +.B FS_XFLAG_EXTSIZE
> +set in
> +.I fsx_xflags
> +and this field is zero, the XFLAG will be cleared instead.
> +.PP
> +.I fsx_nextents
> +is the number of data extents in this file.
> +If
> +.B XFS_IOC_FSGETXATTRA
> +was used, then this is the number of extended attribute extents in the file.
> +.PP
> +.I fsx_projid
> +is the project ID of this file.
> +.PP
> +.I fsx_cowextsize
> +is the preferred extent allocation size for copy on write operations
> +targeting this file, in units of filesystem blocks.
> +If this field is zero, the filesystem will choose a default option,
> +which is currently 128 filesystem blocks.
> +If
> +.B XFS_IOC_FSSETXATTR
> +is called with
> +.B FS_XFLAG_COWEXTSIZE
> +set in
> +.I fsx_xflags
> +and this field is zero, the XFLAG will be cleared instead.
> +
> +.PP
> +.I fsx_pad
> +must be zeroed.
> +
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EACCESS
> +Caller does not have sufficient access to change the attributes.
> +.TP
> +.B EFAULT
> +The kernel was not able to copy into the userspace buffer.
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EINVAL
> +One of the arguments was not valid.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.TP
> +.B ENOMEM
> +There was insufficient memory to perform the query.
> +.TP
> +.B EPERM
> +Caller did not have permission to change the attributes.
> +.SH CONFORMING TO
> +This API is implemented by the ext4, xfs, btrfs, and f2fs filesystems on the
> +Linux kernel.
> +Not all fields may be understood by filesystems other than xfs.
> +.SH SEE ALSO
> +.BR ioctl (2)
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index 462ccbd8..2992b5be 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -132,161 +132,17 @@ will fail with EINVAL.
>  All I/O requests are kept consistent with any data brought into
>  the cache with an access through a non-direct I/O file descriptor.
>  
> -.TP
> -.B XFS_IOC_FSGETXATTR
> -Get additional attributes associated with files in XFS file systems.
> -The final argument points to a variable of type
> -.BR "struct fsxattr" ,
> -whose fields include:
> -.B fsx_xflags
> -(extended flag bits),
> -.B fsx_extsize
> -(nominal extent size in file system blocks),
> -.B fsx_nextents
> -(number of data extents in the file).
> -A
> -.B fsx_extsize
> -value returned indicates that a preferred extent size was previously
> -set on the file, a
> -.B fsx_extsize
> -of zero indicates that the defaults for that filesystem will be used.
> -A
> -.B fsx_cowextsize
> -value returned indicates that a preferred copy on write extent size was
> -previously set on the file, whereas a
> -.B fsx_cowextsize
> -of zero indicates that the defaults for that filesystem will be used.
> -The current default for
> -.B fsx_cowextsize
> -is 128 blocks.
> -Currently the meaningful bits for the
> -.B fsx_xflags
> -field are:
> -.PD 0
> -.RS
> -.TP 1.0i
> -.SM "Bit 0 (0x1) \- XFS_XFLAG_REALTIME"
> -The file is a realtime file.
> -.TP
> -.SM "Bit 1 (0x2) \- XFS_XFLAG_PREALLOC"
> -The file has preallocated space.
> -.TP
> -.SM "Bit 3 (0x8) \- XFS_XFLAG_IMMUTABLE"
> -The file is immutable - it cannot be modified, deleted or renamed,
> -no link can be created to this file and no data can be written to the
> -file.
> -Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
> -capability can set or clear this flag.
> -.TP
> -.SM "Bit 4 (0x10) \- XFS_XFLAG_APPEND"
> -The file is append-only - it can only be open in append mode for
> -writing.
> -Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
> -capability can set or clear this flag.
> -.TP
> -.SM "Bit 5 (0x20) \- XFS_XFLAG_SYNC"
> -All writes to the file are synchronous.
> -.TP
> -.SM "Bit 6 (0x40) \- XFS_XFLAG_NOATIME"
> -When the file is accessed, its atime record is not modified.
> -.TP
> -.SM "Bit 7 (0x80) \- XFS_XFLAG_NODUMP"
> -The file should be skipped by backup utilities.
> -.TP
> -.SM "Bit 8 (0x100) \- XFS_XFLAG_RTINHERIT"
> -Realtime inheritance bit - new files created in the directory
> -will be automatically realtime, and new directories created in
> -the directory will inherit the inheritance bit.
> -.TP
> -.SM "Bit 9 (0x200) \- XFS_XFLAG_PROJINHERIT"
> -Project inheritance bit - new files and directories created in
> -the directory will inherit the parents project ID.  New
> -directories also inherit the project inheritance bit.
> -.TP
> -.SM "Bit 10 (0x400) \- XFS_XFLAG_NOSYMLINKS"
> -Can only be set on a directory and disallows creation of
> -symbolic links in that directory.
> -.TP
> -.SM "Bit 11 (0x800) \- XFS_XFLAG_EXTSIZE"
> -Extent size bit - if a basic extent size value is set on the file
> -then the allocator will allocate in multiples of the set size for
> -this file (see
> -.B XFS_IOC_FSSETXATTR
> -below).
> -.TP
> -.SM "Bit 12 (0x1000) \- XFS_XFLAG_EXTSZINHERIT"
> -Extent size inheritance bit - new files and directories created in
> -the directory will inherit the parents basic extent size value (see
> -.B XFS_IOC_FSSETXATTR
> -below).
> -Can only be set on a directory.
> -.TP
> -.SM "Bit 13 (0x2000) \- XFS_XFLAG_NODEFRAG"
> -No defragment file bit - the file should be skipped during a defragmentation
> -operation. When applied to a directory, new files and directories created will
> -inherit the no\-defrag bit.
> -.TP
> -.SM "Bit 14 (0x4000) \- XFS_XFLAG_FILESTREAM"
> -Filestream allocator bit - allows a directory to reserve an allocation
> -group for exclusive use by files created within that directory. Files
> -being written in other directories will not use the same allocation
> -group and so files within different directories will not interleave
> -extents on disk. The reservation is only active while files are being
> -created and written into the directory.
> -.TP
> -.SM "Bit 15 (0x8000) \- XFS_XFLAG_DAX"
> -If the filesystem lives on directly accessible persistent memory, reads and
> -writes to this file will go straight to the persistent memory, bypassing the
> -page cache.
> -A file cannot be reflinked and have the
> -.BR XFS_XFLAG_DAX
> -set at the same time.
> -That is to say that DAX files cannot share blocks.
> -.TP
> -.SM "Bit 16 (0x10000) \- XFS_XFLAG_COWEXTSIZE"
> -Copy on Write Extent size bit - if a CoW extent size value is set on the file,
> -the allocator will allocate extents for staging a copy on write operation
> -in multiples of the set size for this file (see
> -.B XFS_IOC_FSSETXATTR
> -below).
> -If the CoW extent size is set on a directory, then new file and directories
> -created in the directory will inherit the parent's CoW extent size value.
> -.TP
> -.SM "Bit 31 (0x80000000) \- XFS_XFLAG_HASATTR"
> -The file has extended attributes associated with it.
> -.RE
>  .PP
> -.PD
> -
> -.TP
> -.B XFS_IOC_FSGETXATTRA
> -Identical to
> +.nf
>  .B XFS_IOC_FSGETXATTR
> -except that the
> -.B fsx_nextents
> -field contains the number of attribute extents in the file.
> -
> +.B XFS_IOC_FSGETXATTRA
> +.fi
> +.PD 0
>  .TP
>  .B XFS_IOC_FSSETXATTR
> -Set additional attributes associated with files in XFS file systems.
> -The final argument points to a variable of type
> -.BR "struct fsxattr" ,
> -but only the following fields are used in this call:
> -.BR fsx_xflags ,
> -.BR fsx_extsize ,
> -.BR fsx_cowextsize ,
> -and
> -.BR fsx_projid .
> -The
> -.B fsx_xflags
> -realtime file bit and the file's extent size may be changed only
> -when the file is empty, except in the case of a directory where
> -the extent size can be set at any time (this value is only used
> -for regular file allocations, so should only be set on a directory
> -in conjunction with the XFS_XFLAG_EXTSZINHERIT flag).
> -The copy on write extent size,
> -.BR fsx_cowextsize ,
> -can be set at any time.
> +See
> +.BR ioctl_xfs_fsgetxattr (2)
> +for more information.
>  
>  .TP
>  .B XFS_IOC_GETBMAP
> @@ -649,6 +505,7 @@ The remainder of these operations will not be described further
>  as they are not of general use to applications.
>  
>  .SH SEE ALSO
> +.BR ioctl_xfs_fsgetxattr (2),
>  .BR fstatfs (2),
>  .BR statfs (2),
>  .BR xfs (5),
> 

Re: [PATCH 2/9] libxfs: break out the fsop geometry manpage

[Eric Sandeen]

On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
> 
> Break out the fs geometry ioctl into a separate manpage so that we can
> document how it works.
> 
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
>  man/man2/ioctl_xfs_fsop_geometry.2 |  214 ++++++++++++++++++++++++++++++++++++
>  man/man3/xfsctl.3                  |   11 +-
>  2 files changed, 221 insertions(+), 4 deletions(-)
>  create mode 100644 man/man2/ioctl_xfs_fsop_geometry.2
> 
> 
> diff --git a/man/man2/ioctl_xfs_fsop_geometry.2 b/man/man2/ioctl_xfs_fsop_geometry.2
> new file mode 100644
> index 00000000..4045e03b
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_fsop_geometry.2
> @@ -0,0 +1,214 @@
> +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-FSOP-GEOMETRY 2 2019-04-11 "XFS"
> +.SH NAME
> +ioctl_xfs_fsop_geometry \- report XFS filesystem shape
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_FSOP_GEOMETRY, struct xfs_fsop_geometry *" arg );
> +.PP

ditto on the .br?

also xfs_fsop_geometry isn't a thing, is it?  xfs_fsop_geom?

> +.BI "int ioctl(int " fd ", XFS_IOC_FSOP_GEOMETRY_V1, struct xfs_fsop_geometry_v1 *" arg );

and xfs_fsop_geom_v1

> +.SH DESCRIPTION
> +Report the storage space parameters that influence allocation decisions in
> +this XFS filesystem.
> +This information is conveyed in a structure of the following form:
> +.PP
> +.in +4n
> +.nf
> +struct xfs_fsop_geom {
> +	__u32         blocksize;
> +	__u32         rtextsize;
> +	__u32         agblocks;
> +	__u32         agcount;
> +	__u32         logblocks;
> +	__u32         sectsize;
> +	__u32         inodesize;
> +	__u32         imaxpct;
> +	__u64         datablocks;
> +	__u64         rtblocks;
> +	__u64         rtextents;
> +	__u64         logstart;
> +	unsigned char uuid[16];
> +	__u32         sunit;
> +	__u32         swidth;
> +	__s32         version;
> +	__u32         flags;
> +	__u32         logsectsize;
> +	__u32         rtsectsize;
> +	__u32         dirblocksize;
> +	/* struct xfs_fsop_geom_v1 stops here. */
> +
> +	__u32         logsunit;
> +};
> +.fi
> +.in
> +.PP
> +.I blocksize
> +is the size of a fundamental filesystem block, in bytes.
> +.PP
> +.I rtextsize
> +is the size of an extent on the realtime volume, in bytes.
> +.PP
> +.I agblocks
> +is the size of an allocation group, in units of filesystem blocks.
> +.PP
> +.I agcount
> +is the number of allocation groups in the filesystem.
> +.PP
> +.I logblocks
> +is the size of the log, in units of filesystem blocks.
> +.PP
> +.I sectsize
> +is the smallest amount of data that can be written to the data device
> +atomically, in bytes.
> +.PP
> +.I inodesize
> +is the size of an inode record, in bytes.
> +.PP
> +.I imaxpct
> +is the maximum percentage of the filesystem that can be allocated to inode
> +record blocks.
> +.PP
> +.I datablocks
> +is the size of the data device, in units of filesystem blocks.
> +.PP
> +.I rtblocks
> +is the size of the realtime device, in units of filesystem blocks.
> +.PP
> +.I rtextents
> +is the number of extents that can be allocated on the realtime device.
> +This ought to be
> +.RB "( " rtblocks " * " blocksize " ) / " rtextsize .

ought to be?  I'm not sure what that means?

> +.PP
> +.I logstart
> +tells the start of the log, in units of filesystem blocks.

contains?

> +If the filesystem has an external log, this will be zero.
> +.PP
> +.I uuid
> +is the universal unique identifier of the filesystem.
> +.PP
> +.I sunit
> +is what the filesystem has been told is the size of a RAID stripe unit on the
> +underlying data device, in filesystem blocks.
> +.PP
> +.I swidth
> +is what the filesystem has been told is the width of a RAID stripe on the
> +underlying data device, in units of RAID stripe units.
> +.PP
> +.I version
> +is the version of this structure.
> +This value will be XFS_FSOP_GEOM_VERSION.
> +.PP
> +.I flags
> +tell us what features are enabled on the filesystem.
> +This field can be any combination of the following:
> +.RS 0.4i
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_ATTR
> +Extended attributes are present.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_NLINK
> +This filesystem supports up to 2^32 links.

and if not it supports what?

> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_QUOTA
> +Quotas are enabled.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_IALIGN
> +Inodes are aligned for better performance.

aligned to ____ ? (worth trying to explain?)

> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_DALIGN
> +Data blocks are aligned for better performance.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_SHARED
> +Unused.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_EXTFLG
> +Filesystem supports unwritten extents.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_DIRV2
> +Directories maintain free space data for better performance.

I don't remember all the v1->v2 differences but in other places
you simply say "contains version 2 format" or whatnot, so that might
suffice here.  Also can't do v1 since forever, anyway.  ;)

> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_LOGV2
> +Log uses the V2 format.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_SECTOR
> +The log device has a sector size larger than 512 bytes.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_ATTR2
> +Filesystem contains V2 extended attributes.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_PROJID32
> +Project IDs can be as large as 2^32.

otherwise 2^16?

> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_DIRV2CI
> +Case-insensitive lookups are supported on directories.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_LAZYSB
> +On-disk superblock counters are updated only at unmount time.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_V5SB
> +Metadata blocks are self describing and contain checksums.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_FTYPE
> +Directories cache inode types in directory entries.

s/cache/contain/

> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_FINOBT
> +Filesystem maintains an index of free inodes.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_SPINODES
> +Filesystem tries harder to allocate inodes when free space is fragmented.

Filesystem may allocate discontinuous inode chunks when free space is fragmented?

> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_RMAPBT
> +Filesystem stores reverse mappings of blocks to owners.
> +.TP
> +.B XFS_FSOP_GEOM_FLAGS_REFLINK
> +Filesystem supports sharing blocks.

between inodes?

> +.RE
> +
> +.PD 1
> +.PP
> +.I logsectsize
> +is the smallest amount of data that can be written to the log device atomically,
> +in bytes.

oh hello, we're back to the structure members again!

I wonder if it'd be better to move the flag details down below all the structure descriptions.

> +.PP
> +.I rtsectsize
> +is the smallest amount of data that can be written to the realtime device
> +atomically, in bytes.
> +.PP
> +.I dirblocksize
> +is the size of directory blocks, in bytes.
> +.PP
> +.I logsunit
> +is what the filesystem has been told is the size of a RAID stripe unit on the
> +underlying log device, in filesystem blocks.
> +This field is meaningful only if the flag
> +.B  XFS_FSOP_GEOM_FLAGS_LOGV2
> +is set.
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EFAULT
> +The kernel was not able to copy into the userspace buffer.
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.SH CONFORMING TO
> +This API is specific to XFS filesystem on the Linux kernel.
> +.SH SEE ALSO
> +.BR ioctl (2)
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index 2992b5be..1237eac6 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -479,6 +479,12 @@ the kernel, except no output count parameter is used (should
>  be initialized to zero).
>  An error is returned if the inode number is invalid.
>  
> +.TP
> +.B XFS_IOC_FSGEOMETRY
> +See
> +.BR ioctl_xfs_fsop_geometry (2)
> +for more information.
> +
>  .PP
>  .nf
>  .B XFS_IOC_THAW
> @@ -494,10 +500,6 @@ An error is returned if the inode number is invalid.
>  These interfaces are used to implement various filesystem internal
>  operations on XFS filesystems.
>  For
> -.B XFS_IOC_FSGEOMETRY
> -(get filesystem mkfs time information), the output structure is of type
> -.BR struct xfs_fsop_geom .
> -For
>  .B XFS_FS_COUNTS
>  (get filesystem dynamic global information), the output structure is of type
>  .BR xfs_fsop_counts_t .
> @@ -506,6 +508,7 @@ as they are not of general use to applications.
>  
>  .SH SEE ALSO
>  .BR ioctl_xfs_fsgetxattr (2),
> +.BR ioctl_xfs_fsop_geometry (2),
>  .BR fstatfs (2),
>  .BR statfs (2),
>  .BR xfs (5),
> 

Re: [PATCH 3/9] libxfs: break out the bulkstat manpage

[Eric Sandeen]

On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
> 
> Break out the bulkstat ioctl into a separate manpage so that we can
> document how it works.
> 
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
>  man/man2/ioctl_xfs_fsbulkstat.2 |  212 +++++++++++++++++++++++++++++++++++++++
>  man/man3/xfsctl.3               |   87 +---------------
>  2 files changed, 219 insertions(+), 80 deletions(-)
>  create mode 100644 man/man2/ioctl_xfs_fsbulkstat.2
> 
> 
> diff --git a/man/man2/ioctl_xfs_fsbulkstat.2 b/man/man2/ioctl_xfs_fsbulkstat.2
> new file mode 100644
> index 00000000..8908631a
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_fsbulkstat.2
> @@ -0,0 +1,212 @@
> +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-FSBULKSTAT 2 2019-04-11 "XFS"
> +.SH NAME
> +ioctl_xfs_fsbulkstat \- query information for a batch of XFS inodes
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_FSBULKSTAT, struct xfs_fsop_bulkreq *" arg );
> +.PP

.br   *shrug* maybe not, seems like you have a plan here ;)

> +.BI "int ioctl(int " fd ", XFS_IOC_FSBULKSTAT_SINGLE, struct xfs_fsop_bulkreq *" arg );
> +.SH DESCRIPTION
> +Query stat information for a bunch of XFS inodes.

s/bunch/group/ or s/a bunch of//

> +These ioctls use
> +.B struct xfs_fsop_bulkreq
> +to set up a bulk transfer with the kernel:
> +.PP
> +.in +4n
> +.nf
> +struct xfs_fsop_bulkreq {
> +	__u64             *lastip;
> +	__s32             count;
> +	void              *ubuffer;
> +	__s32             *ocount;
> +};
> +.fi
> +.in
> +.PP
> +.I lastip
> +points to a value that will receive the number of the "last inode".

can it be NULL?

> +For
> +.BR FSBULKSTAT ,
> +this should be set to one less than the number of the first inode for which the
> +caller wants information, or zero to start with the first inode in the
> +filesystem.
> +For
> +.BR FSBULKSTAT_SINGLE ,
> +this should be set to the number of the inode for which the caller wants
> +information.
> +After the call, this value will be set to the number of the last inode for
> +which information was supplied.
> +This field will not be updated if
> +.I ocount
> +is NULL.
> +.PP
> +.I count
> +is the number of inodes to examine.

and the size of the area pointed to by *ubuffer?
(I guess that's covered in the *ubuffer description)

> +This value must be set to 1 for
> +.BR FSBULKSTAT_SINGLE .
> +.PP
> +.I ocount
> +points to a value that will receive the number of records returned.
> +If this value is NULL, then neither
> +.I ocount
> +nor
> +.I lastip
> +will be updated.
> +.PP
> +.I ubuffer
> +points to a memory buffer where information will be copied.

into which inode information will be copied?

> +This buffer must be an array of
> +.B struct xfs_bstat
> +which is described below.
> +The array must have at least
> +.I count
> +elements.
> +.PP
> +.in +4n
> +.nf
> +struct xfs_bstat {
> +	__u64             bs_ino;
> +	__u16             bs_mode;
> +	__u16             bs_nlink;
> +	__u32             bs_uid;
> +	__u32             bs_gid;
> +	__u32             bs_rdev;
> +	__s32             bs_blksize;
> +	__s64             bs_size;
> +	struct xfs_bstime bs_atime;
> +	struct xfs_bstime bs_mtime;
> +	struct xfs_bstime bs_ctime;
> +	int64_t           bs_blocks;
> +	__u32             bs_xflags;
> +	__s32             bs_extsize;
> +	__s32             bs_extents;
> +	__u32             bs_gen;
> +	__u16             bs_projid_lo;
> +	__u16             bs_forkoff;
> +	__u16             bs_projid_hi;
> +	unsigned char     bs_pad[6];
> +	__u32             bs_cowextsize;
> +	__u32             bs_dmevmask;
> +	__u16             bs_dmstate;
> +	__u16             bs_aextents;
> +};
> +.fi
> +.in
> +.PP

The structure members are as follows:

> +.I bs_ino
> +is the number of this inode record.

is the inode number for this record

> +.PP
> +.I bs_mode
> +is the file type and mode.
> +.PP
> +.I bs_nlink
> +is the number of hard links to this inode.
> +.PP
> +.I bs_uid
> +is the user id.
> +.PP
> +.I bs_gid
> +is the group id.
> +.PP
> +.I bs_rdev
> +is the encoded device id if this is a special file.
> +.PP
> +.I bs_blksize
> +is the size of a data block for this file, in units of bytes.
> +.PP
> +.I bs_size
> +is the size of the file, in bytes.
> +.PP
> +.I bs_atime
> +is the last time this file was accessed.
> +.PP
> +.I bs_mtime
> +is the last time the contents of this file were modified.
> +.PP
> +.I bs_ctime
> +is the last time this inode record was modified.
> +.PP
> +.I bs_blocks
> +is the number of filesystem blocks allocated to this file, including metadata.
> +.PP
> +.I bs_xflags
> +tell us what extended flags are set this inode.

contains the extended flags which are set in this inode

> +These flags are the same values as those set in the
> +.I fsx_xflags
> +field of
> +.BR "struct fsxattr" ;
> +please see the
> +.BR ioctl_fsgetxattr (2)
> +manpage for more information.

I dig it but you made an ioctl_xfs_fsgetxattr(2) manpage...

(I forget, how do we alias manpages?)

also this should go in SEE ALSO

> +
> +.PD 1
> +.PP
> +.I bs_extsize
> +is the extent size hint for this file, in bytes.
> +.PP
> +.I bs_extents
> +is the number of storage space extents associated with this file's data.

storage space extents sounds odd...

is the number of data extents in this file.

> +.PP
> +.I bs_gen
> +is the generation number of the inode record.
> +.PP
> +.I bs_projid_lo
> +is the lower 16-bits of the project id.
> +.PP
> +.I bs_forkoff
> +is the offset of the attribute fork in the inode record, in bytes.
> +.PP
> +.I bs_projid_hi
> +is the upper 16-bits of the project id.
> +.PP
> +.I bs_pad[6]
> +is zeroed.
> +.PP
> +.I bs_cowextsize
> +is the Copy on Write extent size hint for this file, in bytes.
> +.PP
> +.I bs_dmevmask
> +is unused on Linux.
> +.PP
> +.I bs_dmstate
> +is unused on Linux.
> +.PP
> +.I bs_aextents
> +is the number of storage space extents associated with this file's extended
> +attributes.

is the number of extended attribute extents in this file?  *shrug*

> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EFAULT
> +The kernel was not able to copy into the userspace buffer.
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EINVAL
> +One of the arguments was not valid.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.TP
> +.B ENOMEM
> +There was insufficient memory to perform the query.
> +.SH CONFORMING TO
> +This API is specific to XFS filesystem on the Linux kernel.
> +.SH SEE ALSO
> +.BR ioctl (2)
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index 1237eac6..94a6ad4b 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -399,92 +399,18 @@ An output
>  .B ocount
>  value of zero means that the inode table has been exhausted.
>  
> -.TP
> -.B XFS_IOC_FSBULKSTAT
> -This interface is used to extract inode information (stat
> -information) "in bulk" from a filesystem.  It is intended to
> -be called iteratively, to obtain information about the entire
> -set of inodes in a filesystem.
> -The information is passed in and out via a structure of type
> -.B xfs_fsop_bulkreq_t
> -pointed to by the final argument.
> -.B lastip
> -is a pointer to a variable containing the last inode number returned,
> -initially it should be zero.
> -.B icount
> -indicates the size of the array of structures specified by
> -.B ubuffer.
> -.B ubuffer
> -is the address of an array of structures of type
> -.BR xfs_bstat_t .
> -Many of the elements in the structure are the same as for the stat
> -structure.
> -The structure has the following elements:
> -.B bs_ino
> -(inode number),
> -.B bs_mode
> -(type and mode),
> -.B bs_nlink
> -(number of links),
> -.B bs_uid
> -(user id),
> -.B bs_gid
> -(group id),
> -.B bs_rdev
> -(device value),
> -.B bs_blksize
> -(block size of the filesystem),
> -.B bs_size
> -(file size in bytes),
> -.B bs_atime
> -(access time),
> -.B bs_mtime
> -(modify time),
> -.B bs_ctime
> -(inode change time),
> -.B bs_blocks
> -(number of blocks used by the file),
> -.B bs_xflags
> -(extended flags),
> -.B bs_extsize
> -(extent size),
> -.B bs_extents
> -(number of extents),
> -.B bs_gen
> -(generation count),
> -.B bs_projid_lo
> -(project id - low word),
> -.B bs_projid_hi
> -(project id - high word, used when projid32bit feature is enabled),
> -.B bs_dmevmask
> -(DMIG event mask),
> -.B bs_dmstate
> -(DMIG state information), and
> -.B bs_aextents
> -(attribute extent count).
> -.B ocount
> -is a pointer to a count of returned values, filled in by the call.
> -An output
> -.B ocount
> -value of zero means that the inode table has been exhausted.
> -
> -.TP
> -.B XFS_IOC_FSBULKSTAT_SINGLE
> -This interface is a variant of the
> -.B XFS_IOC_FSBULKSTAT
> -interface, used to obtain information about a single inode.
> -for an open file in the filesystem of interest.
> -The same structure is used to pass information in and out of
> -the kernel, except no output count parameter is used (should
> -be initialized to zero).
> -An error is returned if the inode number is invalid.
> -
>  .TP
>  .B XFS_IOC_FSGEOMETRY
>  See
>  .BR ioctl_xfs_fsop_geometry (2)
>  for more information.
>  
> +.TP
> +.BR XFS_IOC_FSBULKSTAT " or " XFS_IOC_FSBULKSTAT_SINGLE
> +See
> +.BR ioctl_xfs_fsbulkstat (2)
> +for more information.
> +
>  .PP
>  .nf
>  .B XFS_IOC_THAW
> @@ -509,6 +435,7 @@ as they are not of general use to applications.
>  .SH SEE ALSO
>  .BR ioctl_xfs_fsgetxattr (2),
>  .BR ioctl_xfs_fsop_geometry (2),
> +.BR ioctl_xfs_fsbulkstat (2),
>  .BR fstatfs (2),
>  .BR statfs (2),
>  .BR xfs (5),
> 

Re: [PATCH 1/9] libxfs: break out the GETXATTR/SETXATTR manpage

[Darrick J. Wong]

On Fri, Jun 14, 2019 at 04:17:10PM -0500, Eric Sandeen wrote:
> On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> > 
> > Break out the xfs file attribute get and set ioctls into a separate
> > manpage to reduce clutter in xfsctl.
> 
> <comes up for air>
> 
> Now that we've uh, hoisted it to be a generic vfs interface,
> FS_IOC_FSGETXATTR, shouldn't we be documenting it as that instead
> of the (old) xfs variant?

No, first we document the old xfs ioctl, then we move the manpage over
to the main man-pages.git project as the vfs ioctl, and then we update
the xfsprogs manpage to say "Please refer to the VFS documentation but
in case your system doesn't have it, here you go..." :)

> 
> (honestly that'd be mostly just search and replace for this patch)
> 
> Except of course XFS_IOC_FSGETXATTRA has no vfs variant.  :/
> 
> I also wonder if FS_IOC_SETFLAGS should be mentioned, and/or a
> SEE_ALSO because some of the functionality overlaps?

Oh, wow, there's actually a manpage for it...

...bleh, it's the weekend, I'll respond to the rest later.

--D

> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> >  man/man2/ioctl_xfs_fsgetxattr.2 |  219 +++++++++++++++++++++++++++++++++++++++
> >  man/man3/xfsctl.3               |  159 +---------------------------
> >  2 files changed, 227 insertions(+), 151 deletions(-)
> >  create mode 100644 man/man2/ioctl_xfs_fsgetxattr.2
> > 
> > 
> > diff --git a/man/man2/ioctl_xfs_fsgetxattr.2 b/man/man2/ioctl_xfs_fsgetxattr.2
> > new file mode 100644
> > index 00000000..17276dec
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_fsgetxattr.2
> > @@ -0,0 +1,219 @@
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-FSGETXATTR 2 2019-04-16 "XFS"
> > +.SH NAME
> > +ioctl_xfs_fsgetxattr \- query information for an open file
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <linux/fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTR, struct fsxattr *" arg );
> > +.PP
> 
> maybe
> 
> .br
> 
> here to keep it more compact?  Unless there's a manpage style I'm unaware
> of?
> 
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTRA, struct fsxattr *" arg );
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSSETXATTR, struct fsxattr *" arg );
> > +.SH DESCRIPTION
> > +Query or set additional attributes associated with files in various file
> > +systems.
> 
> (it was the "various filesystems" which caught my eye and reminded me to
> ask the first question)
> 
> > +The attributes are conveyed in a structure of the form:
> > +.PP
> > +.in +4n
> > +.nf
> > +struct fsxattr {
> > +	__u32         fsx_xflags;
> > +	__u32         fsx_extsize;
> > +	__u32         fsx_nextents;
> > +	__u32         fsx_projid;
> > +	__u32         fsx_cowextsize;
> > +	unsigned char fsx_pad[8];
> > +};
> > +.fi
> > +.in
> > +.PP
> > +.I fsx_xflags
> > +are extended flags that apply to this file.
> > +This field can be a combination of the following:
> > +
> > +.RS 0.4i
> > +.TP
> > +.B FS_XFLAG_REALTIME
> > +The file is a realtime file.
> > +This bit can only be changed when the file is empty.
> > +.TP
> > +.B FS_XFLAG_PREALLOC
> > +The file has preallocated space.
> > +.TP
> > +.B FS_XFLAG_IMMUTABLE
> > +The file is immutable - it cannot be modified, deleted or renamed,
> > +no link can be created to this file and no data can be written to the
> > +file.
> > +Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
> > +capability can set or clear this flag.
> > +If this flag is set before a
> > +.B FS_IOC_SETXATTR
> 
> (and here you do refer to the non-XFS variant)
> 
> > +call and would not be cleared by the call, then no other attributes can be
> > +changed and
> > +.B EPERM
> > +will be returned.
> > +.TP
> > +.B FS_XFLAG_APPEND
> > +The file is append-only - it can only be open in append mode for
> > +writing.
> > +Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
> > +capability can set or clear this flag.
> > +.TP
> > +.B FS_XFLAG_SYNC
> > +All writes to the file are synchronous.
> > +.TP
> > +.B FS_XFLAG_NOATIME
> > +When the file is accessed, its atime record is not modified.
> > +.TP
> > +.B FS_XFLAG_NODUMP
> > +The file should be skipped by backup utilities.
> > +.TP
> > +.B FS_XFLAG_RTINHERIT
> > +Realtime inheritance bit - new files created in the directory
> > +will be automatically realtime, and new directories created in
> > +the directory will inherit the inheritance bit.
> > +.TP
> > +.B FS_XFLAG_PROJINHERIT
> > +Project inheritance bit - new files and directories created in
> > +the directory will inherit the parents project ID.
> 
> s/parents/parent directory's/
> 
> > +New directories also inherit the project inheritance bit.
> 
> also may as well keep the text for RTINHERIT and PROJINHERIT
> identical other than the bit name/description.
> 
> > +.TP
> > +.B FS_XFLAG_NOSYMLINKS
> > +Can only be set on a directory and disallows creation of
> > +symbolic links in that directory.
> > +.TP
> > +.B FS_XFLAG_EXTSIZE
> > +Extent size bit - if a basic extent size value is set on the file
> > +then the allocator will allocate in multiples of the set size for
> > +this file (see
> > +.B fsx_extsize
> > +below).
> > +This flag can only be set on a file if it is empty.
> > +.TP
> > +.B FS_XFLAG_EXTSZINHERIT
> > +Extent size inheritance bit - new files and directories created in
> > +the directory will inherit the parents basic extent size value (see
> 
> s/parents/parent directory's/
> 
> again probably keep text same as RTINHERIT/PROJINHERIT modulo bit name.
> 
> > +.B fsx_extsize
> > +below).
> > +Can only be set on a directory.
> 
> (i.e. the others "can only be set on a directory" too right?)
> 
> > +.TP
> > +.B FS_XFLAG_NODEFRAG
> > +No defragment file bit - the file should be skipped during a defragmentation
> > +operation. When applied to a directory, new files and directories created will
> > +inherit the no\-defrag bit.
> > +.TP
> > +.B FS_XFLAG_FILESTREAM
> > +Filestream allocator bit - allows a directory to reserve an allocation group
> > +for exclusive use by files created within that directory.
> > +Files being written in other directories will not use the same allocation group
> > +and so files within different directories will not interleave extents on disk.
> > +The reservation is only active while files are being created and written into
> > +the directory.
> > +.TP
> > +.B FS_XFLAG_DAX
> > +If the filesystem lives on directly accessible persistent memory, reads and
> > +writes to this file will go straight to the persistent memory, bypassing the
> > +page cache.
> > +A file cannot be reflinked and have the
> > +.BR FS_XFLAG_DAX
> > +set at the same time.
> 
> Since you can't even mount that way, I suppose not ....
> 
> > +That is to say that DAX files cannot share blocks.
> > +If this flag is set on a directory, files created within that directory will
> > +have this flag set.
> 
> Documenting DAX is a bold move...
> 
> Do subdirs not inherit the flag?
> 
> 
> > +.TP
> > +.B FS_XFLAG_COWEXTSIZE
> > +Copy on Write Extent size bit - if a CoW extent size value is set on the file,
> > +the allocator will allocate extents for staging a copy on write operation
> > +in multiples of the set size for this file (see
> > +.B fsx_cowextsize
> > +below).
> > +If the CoW extent size is set on a directory, then new file and directories
> > +created in the directory will inherit the parent's CoW extent size value.
> > +.TP
> > +.B FS_XFLAG_HASATTR
> > +The file has extended attributes associated with it.
> > +.RE
> > +.PP
> > +.PD
> > +
> > +.PP
> > +.I fsx_extsize
> > +is the preferred extent allocation size for data blocks mapped to this file,
> > +in units of filesystem blocks.
> > +If this value is zero, the filesystem will choose a default option, which
> > +is currently zero.
> > +If
> > +.B XFS_IOC_FSSETXATTR
> > +is called with
> > +.B FS_XFLAG_EXTSIZE
> > +set in
> > +.I fsx_xflags
> > +and this field is zero, the XFLAG will be cleared instead.
> > +.PP
> > +.I fsx_nextents
> > +is the number of data extents in this file.
> > +If
> > +.B XFS_IOC_FSGETXATTRA
> > +was used, then this is the number of extended attribute extents in the file.
> > +.PP
> > +.I fsx_projid
> > +is the project ID of this file.
> > +.PP
> > +.I fsx_cowextsize
> > +is the preferred extent allocation size for copy on write operations
> > +targeting this file, in units of filesystem blocks.
> > +If this field is zero, the filesystem will choose a default option,
> > +which is currently 128 filesystem blocks.
> > +If
> > +.B XFS_IOC_FSSETXATTR
> > +is called with
> > +.B FS_XFLAG_COWEXTSIZE
> > +set in
> > +.I fsx_xflags
> > +and this field is zero, the XFLAG will be cleared instead.
> > +
> > +.PP
> > +.I fsx_pad
> > +must be zeroed.
> > +
> > +.SH RETURN VALUE
> > +On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error.
> > +.PP
> > +.SH ERRORS
> > +Error codes can be one of, but are not limited to, the following:
> > +.TP
> > +.B EACCESS
> > +Caller does not have sufficient access to change the attributes.
> > +.TP
> > +.B EFAULT
> > +The kernel was not able to copy into the userspace buffer.
> > +.TP
> > +.B EFSBADCRC
> > +Metadata checksum validation failed while performing the query.
> > +.TP
> > +.B EFSCORRUPTED
> > +Metadata corruption was encountered while performing the query.
> > +.TP
> > +.B EINVAL
> > +One of the arguments was not valid.
> > +.TP
> > +.B EIO
> > +An I/O error was encountered while performing the query.
> > +.TP
> > +.B ENOMEM
> > +There was insufficient memory to perform the query.
> > +.TP
> > +.B EPERM
> > +Caller did not have permission to change the attributes.
> > +.SH CONFORMING TO
> > +This API is implemented by the ext4, xfs, btrfs, and f2fs filesystems on the
> > +Linux kernel.
> > +Not all fields may be understood by filesystems other than xfs.
> > +.SH SEE ALSO
> > +.BR ioctl (2)
> > diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> > index 462ccbd8..2992b5be 100644
> > --- a/man/man3/xfsctl.3
> > +++ b/man/man3/xfsctl.3
> > @@ -132,161 +132,17 @@ will fail with EINVAL.
> >  All I/O requests are kept consistent with any data brought into
> >  the cache with an access through a non-direct I/O file descriptor.
> >  
> > -.TP
> > -.B XFS_IOC_FSGETXATTR
> > -Get additional attributes associated with files in XFS file systems.
> > -The final argument points to a variable of type
> > -.BR "struct fsxattr" ,
> > -whose fields include:
> > -.B fsx_xflags
> > -(extended flag bits),
> > -.B fsx_extsize
> > -(nominal extent size in file system blocks),
> > -.B fsx_nextents
> > -(number of data extents in the file).
> > -A
> > -.B fsx_extsize
> > -value returned indicates that a preferred extent size was previously
> > -set on the file, a
> > -.B fsx_extsize
> > -of zero indicates that the defaults for that filesystem will be used.
> > -A
> > -.B fsx_cowextsize
> > -value returned indicates that a preferred copy on write extent size was
> > -previously set on the file, whereas a
> > -.B fsx_cowextsize
> > -of zero indicates that the defaults for that filesystem will be used.
> > -The current default for
> > -.B fsx_cowextsize
> > -is 128 blocks.
> > -Currently the meaningful bits for the
> > -.B fsx_xflags
> > -field are:
> > -.PD 0
> > -.RS
> > -.TP 1.0i
> > -.SM "Bit 0 (0x1) \- XFS_XFLAG_REALTIME"
> > -The file is a realtime file.
> > -.TP
> > -.SM "Bit 1 (0x2) \- XFS_XFLAG_PREALLOC"
> > -The file has preallocated space.
> > -.TP
> > -.SM "Bit 3 (0x8) \- XFS_XFLAG_IMMUTABLE"
> > -The file is immutable - it cannot be modified, deleted or renamed,
> > -no link can be created to this file and no data can be written to the
> > -file.
> > -Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
> > -capability can set or clear this flag.
> > -.TP
> > -.SM "Bit 4 (0x10) \- XFS_XFLAG_APPEND"
> > -The file is append-only - it can only be open in append mode for
> > -writing.
> > -Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
> > -capability can set or clear this flag.
> > -.TP
> > -.SM "Bit 5 (0x20) \- XFS_XFLAG_SYNC"
> > -All writes to the file are synchronous.
> > -.TP
> > -.SM "Bit 6 (0x40) \- XFS_XFLAG_NOATIME"
> > -When the file is accessed, its atime record is not modified.
> > -.TP
> > -.SM "Bit 7 (0x80) \- XFS_XFLAG_NODUMP"
> > -The file should be skipped by backup utilities.
> > -.TP
> > -.SM "Bit 8 (0x100) \- XFS_XFLAG_RTINHERIT"
> > -Realtime inheritance bit - new files created in the directory
> > -will be automatically realtime, and new directories created in
> > -the directory will inherit the inheritance bit.
> > -.TP
> > -.SM "Bit 9 (0x200) \- XFS_XFLAG_PROJINHERIT"
> > -Project inheritance bit - new files and directories created in
> > -the directory will inherit the parents project ID.  New
> > -directories also inherit the project inheritance bit.
> > -.TP
> > -.SM "Bit 10 (0x400) \- XFS_XFLAG_NOSYMLINKS"
> > -Can only be set on a directory and disallows creation of
> > -symbolic links in that directory.
> > -.TP
> > -.SM "Bit 11 (0x800) \- XFS_XFLAG_EXTSIZE"
> > -Extent size bit - if a basic extent size value is set on the file
> > -then the allocator will allocate in multiples of the set size for
> > -this file (see
> > -.B XFS_IOC_FSSETXATTR
> > -below).
> > -.TP
> > -.SM "Bit 12 (0x1000) \- XFS_XFLAG_EXTSZINHERIT"
> > -Extent size inheritance bit - new files and directories created in
> > -the directory will inherit the parents basic extent size value (see
> > -.B XFS_IOC_FSSETXATTR
> > -below).
> > -Can only be set on a directory.
> > -.TP
> > -.SM "Bit 13 (0x2000) \- XFS_XFLAG_NODEFRAG"
> > -No defragment file bit - the file should be skipped during a defragmentation
> > -operation. When applied to a directory, new files and directories created will
> > -inherit the no\-defrag bit.
> > -.TP
> > -.SM "Bit 14 (0x4000) \- XFS_XFLAG_FILESTREAM"
> > -Filestream allocator bit - allows a directory to reserve an allocation
> > -group for exclusive use by files created within that directory. Files
> > -being written in other directories will not use the same allocation
> > -group and so files within different directories will not interleave
> > -extents on disk. The reservation is only active while files are being
> > -created and written into the directory.
> > -.TP
> > -.SM "Bit 15 (0x8000) \- XFS_XFLAG_DAX"
> > -If the filesystem lives on directly accessible persistent memory, reads and
> > -writes to this file will go straight to the persistent memory, bypassing the
> > -page cache.
> > -A file cannot be reflinked and have the
> > -.BR XFS_XFLAG_DAX
> > -set at the same time.
> > -That is to say that DAX files cannot share blocks.
> > -.TP
> > -.SM "Bit 16 (0x10000) \- XFS_XFLAG_COWEXTSIZE"
> > -Copy on Write Extent size bit - if a CoW extent size value is set on the file,
> > -the allocator will allocate extents for staging a copy on write operation
> > -in multiples of the set size for this file (see
> > -.B XFS_IOC_FSSETXATTR
> > -below).
> > -If the CoW extent size is set on a directory, then new file and directories
> > -created in the directory will inherit the parent's CoW extent size value.
> > -.TP
> > -.SM "Bit 31 (0x80000000) \- XFS_XFLAG_HASATTR"
> > -The file has extended attributes associated with it.
> > -.RE
> >  .PP
> > -.PD
> > -
> > -.TP
> > -.B XFS_IOC_FSGETXATTRA
> > -Identical to
> > +.nf
> >  .B XFS_IOC_FSGETXATTR
> > -except that the
> > -.B fsx_nextents
> > -field contains the number of attribute extents in the file.
> > -
> > +.B XFS_IOC_FSGETXATTRA
> > +.fi
> > +.PD 0
> >  .TP
> >  .B XFS_IOC_FSSETXATTR
> > -Set additional attributes associated with files in XFS file systems.
> > -The final argument points to a variable of type
> > -.BR "struct fsxattr" ,
> > -but only the following fields are used in this call:
> > -.BR fsx_xflags ,
> > -.BR fsx_extsize ,
> > -.BR fsx_cowextsize ,
> > -and
> > -.BR fsx_projid .
> > -The
> > -.B fsx_xflags
> > -realtime file bit and the file's extent size may be changed only
> > -when the file is empty, except in the case of a directory where
> > -the extent size can be set at any time (this value is only used
> > -for regular file allocations, so should only be set on a directory
> > -in conjunction with the XFS_XFLAG_EXTSZINHERIT flag).
> > -The copy on write extent size,
> > -.BR fsx_cowextsize ,
> > -can be set at any time.
> > +See
> > +.BR ioctl_xfs_fsgetxattr (2)
> > +for more information.
> >  
> >  .TP
> >  .B XFS_IOC_GETBMAP
> > @@ -649,6 +505,7 @@ The remainder of these operations will not be described further
> >  as they are not of general use to applications.
> >  
> >  .SH SEE ALSO
> > +.BR ioctl_xfs_fsgetxattr (2),
> >  .BR fstatfs (2),
> >  .BR statfs (2),
> >  .BR xfs (5),
> > 

Re: [PATCH 1/9] libxfs: break out the GETXATTR/SETXATTR manpage

[Eric Sandeen]

On 6/15/19 11:43 AM, Darrick J. Wong wrote:
> On Fri, Jun 14, 2019 at 04:17:10PM -0500, Eric Sandeen wrote:
>> On 6/7/19 2:29 PM, Darrick J. Wong wrote:
>>> From: Darrick J. Wong <darrick.wong@oracle.com>
>>>
>>> Break out the xfs file attribute get and set ioctls into a separate
>>> manpage to reduce clutter in xfsctl.
>>
>> <comes up for air>
>>
>> Now that we've uh, hoisted it to be a generic vfs interface,
>> FS_IOC_FSGETXATTR, shouldn't we be documenting it as that instead
>> of the (old) xfs variant?
> 
> No, first we document the old xfs ioctl, then we move the manpage over
> to the main man-pages.git project as the vfs ioctl, and then we update
> the xfsprogs manpage to say "Please refer to the VFS documentation but
> in case your system doesn't have it, here you go..." :)

I guess it's kind of a sad state of affairs that I'm not quite sure
if this is serious.  :)

>>
>> (honestly that'd be mostly just search and replace for this patch)
>>
>> Except of course XFS_IOC_FSGETXATTRA has no vfs variant.  :/
>>
>> I also wonder if FS_IOC_SETFLAGS should be mentioned, and/or a
>> SEE_ALSO because some of the functionality overlaps?
> 
> Oh, wow, there's actually a manpage for it...
> 
> ...bleh, it's the weekend, I'll respond to the rest later.

ok thanks

-Eric

Re: [PATCH 4/9] libxfs: link to the scrub ioctl from xfsctl.3

[Eric Sandeen]

On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
> 
> Link to the scrub ioctl documentation from xfsctl.
> 
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>

Seems like every reference to another man page should also be
explicitly in the SEE ALSO section, no?

(there must be a man page best practices manual somewhere, to be
sure i'm not just making stuff up?)

> ---
>  man/man3/xfsctl.3 |    6 ++++++
>  1 file changed, 6 insertions(+)
> 
> 
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index 94a6ad4b..cdf0fcfc 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -411,6 +411,12 @@ See
>  .BR ioctl_xfs_fsbulkstat (2)
>  for more information.
>  
> +.TP
> +.B XFS_IOC_SCRUB_METADATA
> +See
> +.BR ioctl_xfs_scrub_metadata (2)
> +for more information.
> +
>  .PP
>  .nf
>  .B XFS_IOC_THAW
> 

Re: [PATCH 5/9] libxfs: break out the INUMBERS manpage

[Eric Sandeen]

On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
> 
> Create a separate manual page for the INUMBERS ioctl so we can document
> how it works.
> 
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
>  man/man2/ioctl_xfs_fsinumbers.2 |  115 +++++++++++++++++++++++++++++++++++++++
>  man/man3/xfsctl.3               |   34 +-----------
>  2 files changed, 119 insertions(+), 30 deletions(-)
>  create mode 100644 man/man2/ioctl_xfs_fsinumbers.2
> 
> 
> diff --git a/man/man2/ioctl_xfs_fsinumbers.2 b/man/man2/ioctl_xfs_fsinumbers.2
> new file mode 100644
> index 00000000..86cdf4d9
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_fsinumbers.2
> @@ -0,0 +1,115 @@
> +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-FSINUMBERS 2 2019-04-16 "XFS"
> +.SH NAME
> +ioctl_xfs_fsinumbers \- extract a list of valid inode numbers from an XFS filesystem
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_FSINUMBERS, struct xfs_fsop_bulkreq *" arg );
> +.SH DESCRIPTION
> +Query a list of valid inode numbers from an XFS filesystem.
> +It is intended to be called iteratively to obtain the entire set of inodes.
> +These ioctls use
> +.B struct xfs_fsop_bulkreq
> +to set up a bulk transfer with the kernel:
> +.PP
> +.in +4n
> +.nf
> +struct xfs_fsop_bulkreq {
> +	__u64   *lastip;
> +	__s32   count;
> +	void    *ubuffer;
> +	__s32   *ocount;
> +};
> +.fi
> +.in
> +.PP
> +.I lastip
> +points to a value that will receive the number of the "last inode".
> +This should be set to one less than the number of the first inode for which the
> +caller wants information, or zero to start with the first inode in the
> +filesystem.
> +After the call, this value will be set to the number of the last inode for
> +which information is supplied.
> +This field will not be updated if
> +.I ocount
> +is NULL.
> +.PP
> +.I count
> +is the number of inodes to examine.

again should it have something like "corresponding to the number
of array elements passed in in the ubuffer array?"

> +.PP
> +.I ocount
> +points to a value that will receive the number of records returned.
> +An output value of zero means that there are no more inodes left to enumerate.
> +If this value is NULL, then neither
> +.I ocount
> +nor
> +.I lastip
> +will be updated.
> +.PP
> +.I ubuffer
> +points to a memory buffer where information will be copied.
> +This buffer must be an array of
> +.B struct xfs_inogrp
> +which is described below.
> +The array must have at least
> +.I count
> +elements.
> +.PP
> +.in +4n
> +.nf
> +struct xfs_inogrp {
> +	__u64   xi_startino;
> +	__s32   xi_alloccount;
> +	__u64   xi_allocmask;
> +}
> +.fi
> +.in
> +.PP
> +.I xi_startino
> +is the number of this inode numbers record.

this phrasing confuses me.

xi_startino is the first inode number in this inode... group?

> +Each inode numbers record will correspond roughly to a record in the inode
> +btree, though this is not guaranteed.

I don't think that is useful information.

> +.PP
> +.I xi_alloccount
> +is the number of bits that are set in
> +.IR xi_allocmask .

i.e. the number of inodes in use in this group?

> +.PP
> +.I xi_allocmask
> +is the mask of inodes that are in use for this inode.

inodes that are in use for this inode?  wut.

> +The bitmask is 64 bits long, and the least significant bit corresponds to inode
> +.BR xi_startino .

ok so finally we get to what I consider to be the useful thing that ties it
all together ;)

so maybe best to just say that it returns inode usage information for a group of
64 consecutive inode numbers, starting with inode xi_startino, with a bitmask of
in-use inodes in xi_allocmask, with total in-use inodes for this batch/group/set
shown in xi_alloccount?

> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EFAULT
> +The kernel was not able to copy into the userspace buffer.
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EINVAL
> +One of the arguments was not valid.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.TP
> +.B ENOMEM
> +There was insufficient memory to perform the query.
> +.SH CONFORMING TO
> +This API is specific to XFS filesystem on the Linux kernel.
> +.SH SEE ALSO
> +.BR ioctl (2)
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index cdf0fcfc..148119a9 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -368,36 +368,9 @@ can be any open file in the XFS filesystem in question.
>  .PP
>  .TP
>  .B XFS_IOC_FSINUMBERS
> -This interface is used to extract a list of valid inode numbers from an
> -XFS filesystem.
> -It is intended to be called iteratively, to obtain the entire set of inodes.
> -The information is passed in and out via a structure of type
> -.B xfs_fsop_bulkreq_t
> -pointed to by the final argument.
> -.B lastip
> -is a pointer to a variable containing the last inode number returned,
> -initially it should be zero.
> -.B icount
> -is the size of the array of structures specified by
> -.BR ubuffer .
> -.B ubuffer
> -is the address of an array of structures, of type
> -.BR xfs_inogrp_t .
> -This structure has the following elements:
> -.B xi_startino
> -(starting inode number),
> -.B xi_alloccount
> -(count of bits set in xi_allocmask), and
> -.B xi_allocmask
> -(mask of allocated inodes in this group).
> -The bitmask is 64 bits long, and the least significant bit corresponds to inode
> -.B xi_startino.
> -Each bit is set if the corresponding inode is in use.
> -.B ocount
> -is a pointer to a count of returned values, filled in by the call.
> -An output
> -.B ocount
> -value of zero means that the inode table has been exhausted.
> +See
> +.BR ioctl_xfs_fsinumbers (2)
> +for more information.
>  
>  .TP
>  .B XFS_IOC_FSGEOMETRY
> @@ -442,6 +415,7 @@ as they are not of general use to applications.
>  .BR ioctl_xfs_fsgetxattr (2),
>  .BR ioctl_xfs_fsop_geometry (2),
>  .BR ioctl_xfs_fsbulkstat (2),
> +.BR ioctl_xfs_fsinumbers (2),
>  .BR fstatfs (2),
>  .BR statfs (2),
>  .BR xfs (5),
> 

Re: [PATCH 6/9] libxfs: break out FSCOUNTS manpage

[Eric Sandeen]

On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
> 
> Create a separate manual page for the FSCOUNTS ioctl so we can document
> how it works.
> 
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
>  man/man2/ioctl_xfs_fscounts.2 |   67 +++++++++++++++++++++++++++++++++++++++++
>  man/man3/xfsctl.3             |   14 +++++----
>  2 files changed, 75 insertions(+), 6 deletions(-)
>  create mode 100644 man/man2/ioctl_xfs_fscounts.2
> 
> 
> diff --git a/man/man2/ioctl_xfs_fscounts.2 b/man/man2/ioctl_xfs_fscounts.2
> new file mode 100644
> index 00000000..44b214a1
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_fscounts.2
> @@ -0,0 +1,67 @@
> +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-FSCOUNTS 2 2019-04-16 "XFS"
> +.SH NAME
> +ioctl_xfs_fscounts \- query XFS summary counter information
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_FSCOUNTS, struct xfs_fsop_counts *" arg );
> +.SH DESCRIPTION
> +Query the raw filesystem summary counters.
> +Unlike
> +.BR statvfs (3),
> +the values returned here are the raw values, which do not reflect any
> +alterations or limits set by quotas.

it's altered by /project/ quotas specifically, right?  Should that be
made clear?  Or is it more than just project?

> +The counter information is conveyed in a structure of the following form:
> +.PP
> +.in +4n
> +.nf
> +struct xfs_fscounts {

xfs_fsop_counts?

(this is the second time there's a misnamed structure (I think?)
so I feel like double checking them all is in order unless i'm
missing something?)

> +	__u64   freedata;
> +	__u64   freertx;
> +	__u64   freeino;
> +	__u64   allocino;
> +};
> +.fi
> +.in
> +.PP
> +.I freedata
> +is the number of free filesystem blocks on the data device.
> +.PP
> +.I freertx
> +is the number of free xtents on the realtime device.

extents

> +.PP
> +.I freeino
> +is the number of inode records that are not in use within the space that has
> +been allocated for them.
> +.PP
> +.I allocino
> +is the number of inode records for which space has been allocated.
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EINVAL
> +The specified allocation group number is not valid for this filesystem.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.SH CONFORMING TO
> +This API is specific to XFS filesystem on the Linux kernel.
> +.SH SEE ALSO
> +.BR ioctl (2)
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index 148119a9..007f7d58 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -390,6 +390,12 @@ See
>  .BR ioctl_xfs_scrub_metadata (2)
>  for more information.
>  
> +.TP
> +.B XFS_IOC_FSCOUNTS
> +See
> +.BR ioctl_xfs_fscounts (2)
> +for more information.
> +
>  .PP
>  .nf
>  .B XFS_IOC_THAW
> @@ -398,16 +404,11 @@ for more information.
>  .B XFS_IOC_SET_RESBLKS
>  .B XFS_IOC_FSGROWFSDATA
>  .B XFS_IOC_FSGROWFSLOG
> -.B XFS_IOC_FSGROWFSRT
>  .fi
>  .TP
> -.B XFS_IOC_FSCOUNTS
> +.B XFS_IOC_FSGROWFSRT
>  These interfaces are used to implement various filesystem internal
>  operations on XFS filesystems.
> -For
> -.B XFS_FS_COUNTS
> -(get filesystem dynamic global information), the output structure is of type
> -.BR xfs_fsop_counts_t .
>  The remainder of these operations will not be described further
>  as they are not of general use to applications.
>  
> @@ -416,6 +417,7 @@ as they are not of general use to applications.
>  .BR ioctl_xfs_fsop_geometry (2),
>  .BR ioctl_xfs_fsbulkstat (2),
>  .BR ioctl_xfs_fsinumbers (2),
> +.BR ioctl_xfs_fscounts (2),
>  .BR fstatfs (2),
>  .BR statfs (2),
>  .BR xfs (5),
> 

Re: [PATCH 7/9] libxfs: break out the RESBLKS manpage

[Eric Sandeen]

On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
> 
> Create a separate manual page for the RESBLKS ioctls so we can document
> how they work.
> 
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
>  man/man2/ioctl_xfs_getresblks.2 |   65 +++++++++++++++++++++++++++++++++++++++
>  man/man3/xfsctl.3               |   14 +++++++-
>  2 files changed, 77 insertions(+), 2 deletions(-)
>  create mode 100644 man/man2/ioctl_xfs_getresblks.2
> 
> 
> diff --git a/man/man2/ioctl_xfs_getresblks.2 b/man/man2/ioctl_xfs_getresblks.2
> new file mode 100644
> index 00000000..57533927
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_getresblks.2
> @@ -0,0 +1,65 @@
> +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-GETRESBLKS 2 2019-04-16 "XFS"
> +.SH NAME
> +ioctl_xfs_getresblks \- query XFS summary counter information
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_GET_RESBLKS, struct xfs_fsop_resblks *" arg );
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_SET_RESBLKS, struct xfs_fsop_resblks *" arg );
> +.SH DESCRIPTION
> +Query or set the free space reservation information.
> +These blocks are reserved by the filesystem as a last-ditch attempt to prevent

last-ditch is a bit colloquial and possibly not fun for translators?

s/a last-ditch/an/

> +metadata update failures due to insufficient space.
> +Only the system administrator can call these ioctls, because overriding the
> +defaults is extremely dangerous and should never be tried by anyone.
> +.PP
> +The reservation information is conveyed in a structure of the following form:
> +.PP
> +.in +4n
> +.nf
> +struct xfs_fsop_resblks {
> +	__u64  resblks;
> +	__u64  resblks_avail;
> +};
> +.fi
> +.in
> +.PP
> +.I resblks
> +is the number of blocks that the filesystem will try to maintain to prevent
> +critical out of space situations.
> +.PP
> +.I resblks_avail
> +is the number of reserved blocks remaining.
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EINVAL
> +The specified allocation group number is not valid for this filesystem.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.TP
> +.B EPERM
> +Caller does not have permission to call this ioctl.
> +.SH CONFORMING TO
> +This API is specific to XFS filesystem on the Linux kernel.
> +.SH SEE ALSO
> +.BR ioctl (2)
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index 007f7d58..25e51417 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -396,12 +396,21 @@ See
>  .BR ioctl_xfs_fscounts (2)
>  for more information.
>  
> +.TP
> +.nf
> +.B XFS_IOC_GET_RESBLKS
> +.fi
> +.TP
> +.B XFS_IOC_SET_RESBLKS
> +See
> +.BR ioctl_xfs_getresblks (2)
> +for more information.
> +Save yourself a lot of frustration and avoid these ioctls.
> +
>  .PP
>  .nf
>  .B XFS_IOC_THAW
>  .B XFS_IOC_FREEZE
> -.B XFS_IOC_GET_RESBLKS
> -.B XFS_IOC_SET_RESBLKS
>  .B XFS_IOC_FSGROWFSDATA
>  .B XFS_IOC_FSGROWFSLOG
>  .fi
> @@ -418,6 +427,7 @@ as they are not of general use to applications.
>  .BR ioctl_xfs_fsbulkstat (2),
>  .BR ioctl_xfs_fsinumbers (2),
>  .BR ioctl_xfs_fscounts (2),
> +.BR ioctl_xfs_getresblks (2),
>  .BR fstatfs (2),
>  .BR statfs (2),
>  .BR xfs (5),
> 

Re: [PATCH 8/9] libxfs: break out GETBMAP manpage

[Eric Sandeen]

On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
> 
> Create a separate manual page for the BMAP ioctls so we can document how
> they work.
> 
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
>  man/man2/ioctl_xfs_getbmap.2 |  165 ++++++++++++++++++++++++++++++++++++++++++
>  man/man3/xfsctl.3            |   61 +++-------------
>  2 files changed, 175 insertions(+), 51 deletions(-)
>  create mode 100644 man/man2/ioctl_xfs_getbmap.2
> 
> 
> diff --git a/man/man2/ioctl_xfs_getbmap.2 b/man/man2/ioctl_xfs_getbmap.2
> new file mode 100644
> index 00000000..5097173b
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_getbmap.2
> @@ -0,0 +1,165 @@
> +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-GETBMAP 2 2019-04-11 "XFS"
> +.SH NAME
> +ioctl_xfs_getbmap \- query extent information for an open file
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_GETBMAP, struct getbmap *" arg );
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_GETBMAPA, struct getbmap *" arg );
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_GETBMAPX, struct getbmapx *" arg );
> +.SH DESCRIPTION
> +Get the block map for a segment of a file in an XFS file system.
> +The mapping information is conveyed in a structure of the following form:
> +.PP
> +.in +4n
> +.nf
> +struct getbmap {
> +	__s64   bmv_offset;
> +	__s64   bmv_block;
> +	__s64   bmv_length;
> +	__s32   bmv_count;
> +	__s32   bmv_entries;
> +};
> +.fi
> +.in
> +.PP
> +The
> +.B XFS_IOC_GETBMAPX
> +ioctl uses a larger version of that structure:
> +.PP
> +.in +4n
> +.nf
> +struct getbmapx {
> +	__s64   bmv_offset;
> +	__s64   bmv_block;
> +	__s64   bmv_length;
> +	__s32   bmv_count;
> +	__s32   bmv_entries;
> +	__s32   bmv_iflags;
> +	__s32   bmv_oflags;
> +	__s32   bmv_unused1;
> +	__s32   bmv_unused2;
> +};
> +.fi
> +.in
> +.PP
> +All sizes and offsets in the structure are in units of 512 bytes.
> +.PP
> +The first structure in the array is a header and the remaining structures in
> +the array contain block map information on return.
> +The header controls iterative calls to the command and should be filled out as
> +follows:
> +.TP
> +.B bmv_offset
> +The file offset of the area of interest in the file.
> +.TP
> +.B bmv_length
> +The length of the area of interest in the file.
> +If this value is set to -1, the length of the interesting area is the rest of
> +the file.
> +.TP
> +.B bmv_count
> +The length of the array, including this header.
> +.TP
> +.B bmv_entries
> +The number of entries actually filled in by the call.
> +This does not need to be filled out before the call.
> +.TP
> +.B bmv_iflags
> +For the
> +.B XFS_IOC_GETBMAPX
> +function, this is a combination of the following flags:

specifically mention that they are ORed or is that obvious?

> +.RS 0.4i
> +.TP
> +.B BMV_IF_ATTRFORK
> +Return information about the extended attribute fork.
> +.TP
> +.B BMV_IF_PREALLOC
> +Return information about unwritten pre-allocated segments.
> +.TP
> +.B BMV_IF_DELALLOC
> +Return information about delayed allocation reservation segments.
> +.TP
> +.B BMV_IF_NO_HOLES
> +Do not return information about holes.
> +.RE
> +.PD 1

perhaps mention that others (bmv_block ...) are ignored in the header?

> +
> +.PP
> +On return from a call, the header is updated so that the command can be
> +reused to obtain more information without re-initializing the structures.
> +The remainder of the array will be filled out by the call as follows:
> +
> +.TP
> +.B bmv_offset
> +File offset of segment.
> +.TP
> +.B bmv_block
> +Physical starting block of segment.
> +If this is -1, then the segment is a hole.
> +.TP
> +.B bmv_length
> +Length of segment.
> +.TP
> +.B bmv_oflags
> +The
> +.B XFS_IOC_GETBMAPX
> +function will fill this field with a combination of the following flags:
> +.RS 0.4i
> +.TP
> +.B BMV_OF_PREALLOC
> +The segment is an unwritten pre-allocation.
> +.TP
> +.B BMV_OF_DELALLOC
> +The segment is a delayed allocation reservation.
> +.TP
> +.B BMV_OF_LAST
> +This segment is the last in the file.
> +.TP
> +.B BMV_OF_SHARED
> +This segment shares blocks with other files.
> +.RE
> +.PD 1
> +.PP

.. and maybe mention that i.e. bmv_count is unused in the
array of records? *shrug*

> +The
> +.B XFS_IOC_GETBMAPA
> +command is identical to
> +.B XFS_IOC_GETBMAP
> +except that information about the attribute fork of the file is returned.
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EFAULT
> +The kernel was not able to copy into the userspace buffer.
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EINVAL
> +One of the arguments was not valid.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.TP
> +.B ENOMEM
> +There was insufficient memory to perform the query.
> +.SH CONFORMING TO
> +This API is specific to XFS filesystem on the Linux kernel.
> +.SH SEE ALSO
> +.BR ioctl (2)
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index 25e51417..e0986afb 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -144,59 +144,17 @@ See
>  .BR ioctl_xfs_fsgetxattr (2)
>  for more information.
>  
> -.TP
> -.B XFS_IOC_GETBMAP
> -Get the block map for a segment of a file in an XFS file system.
> -The final argument points to an arry of variables of type
> -.BR "struct getbmap" .
> -All sizes and offsets in the structure are in units of 512 bytes.
> -The structure fields include:
> -.B bmv_offset
> -(file offset of segment),
> -.B bmv_block
> -(starting block of segment),
> -.B bmv_length
> -(length of segment),
> -.B bmv_count
> -(number of array entries, including the first), and
> -.B bmv_entries
> -(number of entries filled in).
> -The first structure in the array is a header, and the remaining
> -structures in the array contain block map information on return.
> -The header controls iterative calls to the
> +.PP
> +.nf
>  .B XFS_IOC_GETBMAP
> -command.
> -The caller fills in the
> -.B bmv_offset
> -and
> -.B bmv_length
> -fields of the header to indicate the area of interest in the file,
> -and fills in the
> -.B bmv_count
> -field to indicate the length of the array.
> -If the
> -.B bmv_length
> -value is set to \-1 then the length of the interesting area is the rest
> -of the file.
> -On return from a call, the header is updated so that the command can be
> -reused to obtain more information, without re-initializing the structures.
> -Also on return, the
> -.B bmv_entries
> -field of the header is set to the number of array entries actually filled in.
> -The non-header structures will be filled in with
> -.BR bmv_offset ,
> -.BR bmv_block ,
> -and
> -.BR bmv_length .
> -If a region of the file has no blocks (is a hole in the file) then the
> -.B bmv_block
> -field is set to \-1.
> -
> -.TP
>  .B XFS_IOC_GETBMAPA
> -Identical to
> -.B XFS_IOC_GETBMAP
> -except that information about the attribute fork of the file is returned.
> +.fi
> +.PD 0
> +.TP
> +.B XFS_IOC_GETBMAPX
> +See
> +.BR ioctl_getbmap (2)
> +for more information.
>  
>  .PP
>  .B XFS_IOC_RESVSP
> @@ -428,6 +386,7 @@ as they are not of general use to applications.
>  .BR ioctl_xfs_fsinumbers (2),
>  .BR ioctl_xfs_fscounts (2),
>  .BR ioctl_xfs_getresblks (2),
> +.BR ioctl_xfs_getbmap (2),
>  .BR fstatfs (2),
>  .BR statfs (2),
>  .BR xfs (5),
> 

Re: [PATCH 9/9] libxfs: break out fs shutdown manpage

[Eric Sandeen]

On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
> 
> Create a separate manual page for the fs shutdown ioctl so we can
> document how it works.
> 
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
>  man/man2/ioctl_xfs_goingdown.2 |   61 ++++++++++++++++++++++++++++++++++++++++
>  man/man3/xfsctl.3              |    7 +++++
>  2 files changed, 68 insertions(+)
>  create mode 100644 man/man2/ioctl_xfs_goingdown.2
> 
> 
> diff --git a/man/man2/ioctl_xfs_goingdown.2 b/man/man2/ioctl_xfs_goingdown.2
> new file mode 100644
> index 00000000..e9a56f28
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_goingdown.2
> @@ -0,0 +1,61 @@
> +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-GOINGDOWN 2 2019-04-16 "XFS"
> +.SH NAME
> +ioctl_xfs_goingdown \- shut down an XFS filesystem
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_GOINGDOWN, uint32_t " flags );
> +.SH DESCRIPTION
> +Shuts down a live XFS filesystem.
> +This is a software initiated hard shutdown and should be avoided whenever
> +possible.
> +After this call completes, the filesystem will be totally unusable and must be
> +unmounted.
> +
> +.PP
> +.I flags
> +can be one of the following:
> +.RS 0.4i
> +.TP
> +.B XFS_FSOP_GOING_FLAGS_DEFAULT
> +Flush all dirty data and in-core state to disk, flush the log, then shut down.
> +.TP
> +.B XFS_FSOP_GOING_FLAGS_LOGFLUSH
> +Flush all pending transactions to the log, then shut down, leaving all dirty
> +data unwritten.
> +.TP
> +.B XFS_FSOP_GOING_FLAGS_NOLOGFLUSH
> +Shut down, leaving all dirty transactions and dirty data.

leaving it ... what?

Maybe "Shut down, without flushing any dirty transactions or data to disk."

> +
> +.SH RETURN VALUE
> +On error, \-1 is returned, and
> +.I errno
> +is set to indicate the error.
> +.PP
> +.SH ERRORS
> +Error codes can be one of, but are not limited to, the following:
> +.TP
> +.B EFSBADCRC
> +Metadata checksum validation failed while performing the query.
> +.TP
> +.B EFSCORRUPTED
> +Metadata corruption was encountered while performing the query.
> +.TP
> +.B EINVAL
> +The specified allocation group number is not valid for this filesystem.
> +.TP
> +.B EIO
> +An I/O error was encountered while performing the query.
> +.TP
> +.B EPERM
> +Caller did not have permission to shut down the filesystem.
> +.SH CONFORMING TO
> +This API is specific to XFS filesystem on the Linux kernel.
> +.SH SEE ALSO
> +.BR ioctl (2)
> diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> index e0986afb..ca96a007 100644
> --- a/man/man3/xfsctl.3
> +++ b/man/man3/xfsctl.3
> @@ -365,6 +365,12 @@ See
>  for more information.
>  Save yourself a lot of frustration and avoid these ioctls.
>  
> +.TP
> +.B XFS_IOC_GOINGDOWN
> +See
> +.BR ioctl_xfs_goingdown (2)
> +for more information.
> +
>  .PP
>  .nf
>  .B XFS_IOC_THAW
> @@ -387,6 +393,7 @@ as they are not of general use to applications.
>  .BR ioctl_xfs_fscounts (2),
>  .BR ioctl_xfs_getresblks (2),
>  .BR ioctl_xfs_getbmap (2),
> +.BR ioctl_xfs_goingdown (2),
>  .BR fstatfs (2),
>  .BR statfs (2),
>  .BR xfs (5),
> 

Re: [PATCH 1/9] libxfs: break out the GETXATTR/SETXATTR manpage

[Darrick J. Wong]

On Mon, Jun 17, 2019 at 09:55:44AM -0500, Eric Sandeen wrote:
> On 6/15/19 11:43 AM, Darrick J. Wong wrote:
> > On Fri, Jun 14, 2019 at 04:17:10PM -0500, Eric Sandeen wrote:
> >> On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> >>> From: Darrick J. Wong <darrick.wong@oracle.com>
> >>>
> >>> Break out the xfs file attribute get and set ioctls into a separate
> >>> manpage to reduce clutter in xfsctl.
> >>
> >> <comes up for air>
> >>
> >> Now that we've uh, hoisted it to be a generic vfs interface,
> >> FS_IOC_FSGETXATTR, shouldn't we be documenting it as that instead
> >> of the (old) xfs variant?
> > 
> > No, first we document the old xfs ioctl, then we move the manpage over
> > to the main man-pages.git project as the vfs ioctl, and then we update
> > the xfsprogs manpage to say "Please refer to the VFS documentation but
> > in case your system doesn't have it, here you go..." :)
> 
> I guess it's kind of a sad state of affairs that I'm not quite sure
> if this is serious.  :)

It is, because the other implementers of this ioctl are not maintaining
the same behavior as xfs.  The first step to doing that is to document
our behaviors, and then get the code under testing.

Granted, those users (ext4/f2fs) aren't using most of the fields or
flags anyway so there's not a lot to test...

--D

> >>
> >> (honestly that'd be mostly just search and replace for this patch)
> >>
> >> Except of course XFS_IOC_FSGETXATTRA has no vfs variant.  :/
> >>
> >> I also wonder if FS_IOC_SETFLAGS should be mentioned, and/or a
> >> SEE_ALSO because some of the functionality overlaps?
> > 
> > Oh, wow, there's actually a manpage for it...
> > 
> > ...bleh, it's the weekend, I'll respond to the rest later.
> 
> ok thanks
> 
> -Eric

Re: [PATCH 1/9] libxfs: break out the GETXATTR/SETXATTR manpage

[Darrick J. Wong]

On Fri, Jun 14, 2019 at 04:17:10PM -0500, Eric Sandeen wrote:
> On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> > 
> > Break out the xfs file attribute get and set ioctls into a separate
> > manpage to reduce clutter in xfsctl.
> 
> <comes up for air>
> 
> Now that we've uh, hoisted it to be a generic vfs interface,
> FS_IOC_FSGETXATTR, shouldn't we be documenting it as that instead
> of the (old) xfs variant?
> 
> (honestly that'd be mostly just search and replace for this patch)
> 
> Except of course XFS_IOC_FSGETXATTRA has no vfs variant.  :/

Hm, I just realized that "man ioctl_xfs_fssetxattr" would fail because
there are no redirect files.  I'll add those.

> I also wonder if FS_IOC_SETFLAGS should be mentioned, and/or a
> SEE_ALSO because some of the functionality overlaps?

Fixed.

> 
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> >  man/man2/ioctl_xfs_fsgetxattr.2 |  219 +++++++++++++++++++++++++++++++++++++++
> >  man/man3/xfsctl.3               |  159 +---------------------------
> >  2 files changed, 227 insertions(+), 151 deletions(-)
> >  create mode 100644 man/man2/ioctl_xfs_fsgetxattr.2
> > 
> > 
> > diff --git a/man/man2/ioctl_xfs_fsgetxattr.2 b/man/man2/ioctl_xfs_fsgetxattr.2
> > new file mode 100644
> > index 00000000..17276dec
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_fsgetxattr.2
> > @@ -0,0 +1,219 @@
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-FSGETXATTR 2 2019-04-16 "XFS"
> > +.SH NAME
> > +ioctl_xfs_fsgetxattr \- query information for an open file
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <linux/fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTR, struct fsxattr *" arg );
> > +.PP
> 
> maybe
> 
> .br
> 
> here to keep it more compact?  Unless there's a manpage style I'm unaware
> of?

Ok.

> > +.BI "int ioctl(int " fd ", XFS_IOC_FSGETXATTRA, struct fsxattr *" arg );
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSSETXATTR, struct fsxattr *" arg );
> > +.SH DESCRIPTION
> > +Query or set additional attributes associated with files in various file
> > +systems.
> 
> (it was the "various filesystems" which caught my eye and reminded me to
> ask the first question)
> 
> > +The attributes are conveyed in a structure of the form:
> > +.PP
> > +.in +4n
> > +.nf
> > +struct fsxattr {
> > +	__u32         fsx_xflags;
> > +	__u32         fsx_extsize;
> > +	__u32         fsx_nextents;
> > +	__u32         fsx_projid;
> > +	__u32         fsx_cowextsize;
> > +	unsigned char fsx_pad[8];
> > +};
> > +.fi
> > +.in
> > +.PP
> > +.I fsx_xflags
> > +are extended flags that apply to this file.
> > +This field can be a combination of the following:
> > +
> > +.RS 0.4i
> > +.TP
> > +.B FS_XFLAG_REALTIME
> > +The file is a realtime file.
> > +This bit can only be changed when the file is empty.
> > +.TP
> > +.B FS_XFLAG_PREALLOC
> > +The file has preallocated space.
> > +.TP
> > +.B FS_XFLAG_IMMUTABLE
> > +The file is immutable - it cannot be modified, deleted or renamed,
> > +no link can be created to this file and no data can be written to the
> > +file.
> > +Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
> > +capability can set or clear this flag.
> > +If this flag is set before a
> > +.B FS_IOC_SETXATTR
> 
> (and here you do refer to the non-XFS variant)

Oops, fixed to refer to the xfs variant.

> > +call and would not be cleared by the call, then no other attributes can be
> > +changed and
> > +.B EPERM
> > +will be returned.
> > +.TP
> > +.B FS_XFLAG_APPEND
> > +The file is append-only - it can only be open in append mode for
> > +writing.
> > +Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
> > +capability can set or clear this flag.
> > +.TP
> > +.B FS_XFLAG_SYNC
> > +All writes to the file are synchronous.
> > +.TP
> > +.B FS_XFLAG_NOATIME
> > +When the file is accessed, its atime record is not modified.
> > +.TP
> > +.B FS_XFLAG_NODUMP
> > +The file should be skipped by backup utilities.
> > +.TP
> > +.B FS_XFLAG_RTINHERIT
> > +Realtime inheritance bit - new files created in the directory
> > +will be automatically realtime, and new directories created in
> > +the directory will inherit the inheritance bit.
> > +.TP
> > +.B FS_XFLAG_PROJINHERIT
> > +Project inheritance bit - new files and directories created in
> > +the directory will inherit the parents project ID.
> 
> s/parents/parent directory's/
> 
> > +New directories also inherit the project inheritance bit.
> 
> also may as well keep the text for RTINHERIT and PROJINHERIT
> identical other than the bit name/description.
> 
> > +.TP
> > +.B FS_XFLAG_NOSYMLINKS
> > +Can only be set on a directory and disallows creation of
> > +symbolic links in that directory.
> > +.TP
> > +.B FS_XFLAG_EXTSIZE
> > +Extent size bit - if a basic extent size value is set on the file
> > +then the allocator will allocate in multiples of the set size for
> > +this file (see
> > +.B fsx_extsize
> > +below).
> > +This flag can only be set on a file if it is empty.
> > +.TP
> > +.B FS_XFLAG_EXTSZINHERIT
> > +Extent size inheritance bit - new files and directories created in
> > +the directory will inherit the parents basic extent size value (see
> 
> s/parents/parent directory's/
> 
> again probably keep text same as RTINHERIT/PROJINHERIT modulo bit name.
> 
> > +.B fsx_extsize
> > +below).
> > +Can only be set on a directory.
> 
> (i.e. the others "can only be set on a directory" too right?)

Ok I'll document and standardize the wording for all the inheritance
behaviors.

> > +.TP
> > +.B FS_XFLAG_NODEFRAG
> > +No defragment file bit - the file should be skipped during a defragmentation
> > +operation. When applied to a directory, new files and directories created will
> > +inherit the no\-defrag bit.
> > +.TP
> > +.B FS_XFLAG_FILESTREAM
> > +Filestream allocator bit - allows a directory to reserve an allocation group
> > +for exclusive use by files created within that directory.
> > +Files being written in other directories will not use the same allocation group
> > +and so files within different directories will not interleave extents on disk.
> > +The reservation is only active while files are being created and written into
> > +the directory.
> > +.TP
> > +.B FS_XFLAG_DAX
> > +If the filesystem lives on directly accessible persistent memory, reads and
> > +writes to this file will go straight to the persistent memory, bypassing the
> > +page cache.
> > +A file cannot be reflinked and have the
> > +.BR FS_XFLAG_DAX
> > +set at the same time.
> 
> Since you can't even mount that way, I suppose not ....
> 
> > +That is to say that DAX files cannot share blocks.
> > +If this flag is set on a directory, files created within that directory will
> > +have this flag set.
> 
> Documenting DAX is a bold move...

<shrug> We introduced an on disk flag and a behavior, now we're stuck
with it unless there's a /really/ good reason to change it.

> Do subdirs not inherit the flag?

They do.

--D

> > +.TP
> > +.B FS_XFLAG_COWEXTSIZE
> > +Copy on Write Extent size bit - if a CoW extent size value is set on the file,
> > +the allocator will allocate extents for staging a copy on write operation
> > +in multiples of the set size for this file (see
> > +.B fsx_cowextsize
> > +below).
> > +If the CoW extent size is set on a directory, then new file and directories
> > +created in the directory will inherit the parent's CoW extent size value.
> > +.TP
> > +.B FS_XFLAG_HASATTR
> > +The file has extended attributes associated with it.
> > +.RE
> > +.PP
> > +.PD
> > +
> > +.PP
> > +.I fsx_extsize
> > +is the preferred extent allocation size for data blocks mapped to this file,
> > +in units of filesystem blocks.
> > +If this value is zero, the filesystem will choose a default option, which
> > +is currently zero.
> > +If
> > +.B XFS_IOC_FSSETXATTR
> > +is called with
> > +.B FS_XFLAG_EXTSIZE
> > +set in
> > +.I fsx_xflags
> > +and this field is zero, the XFLAG will be cleared instead.
> > +.PP
> > +.I fsx_nextents
> > +is the number of data extents in this file.
> > +If
> > +.B XFS_IOC_FSGETXATTRA
> > +was used, then this is the number of extended attribute extents in the file.
> > +.PP
> > +.I fsx_projid
> > +is the project ID of this file.
> > +.PP
> > +.I fsx_cowextsize
> > +is the preferred extent allocation size for copy on write operations
> > +targeting this file, in units of filesystem blocks.
> > +If this field is zero, the filesystem will choose a default option,
> > +which is currently 128 filesystem blocks.
> > +If
> > +.B XFS_IOC_FSSETXATTR
> > +is called with
> > +.B FS_XFLAG_COWEXTSIZE
> > +set in
> > +.I fsx_xflags
> > +and this field is zero, the XFLAG will be cleared instead.
> > +
> > +.PP
> > +.I fsx_pad
> > +must be zeroed.
> > +
> > +.SH RETURN VALUE
> > +On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error.
> > +.PP
> > +.SH ERRORS
> > +Error codes can be one of, but are not limited to, the following:
> > +.TP
> > +.B EACCESS
> > +Caller does not have sufficient access to change the attributes.
> > +.TP
> > +.B EFAULT
> > +The kernel was not able to copy into the userspace buffer.
> > +.TP
> > +.B EFSBADCRC
> > +Metadata checksum validation failed while performing the query.
> > +.TP
> > +.B EFSCORRUPTED
> > +Metadata corruption was encountered while performing the query.
> > +.TP
> > +.B EINVAL
> > +One of the arguments was not valid.
> > +.TP
> > +.B EIO
> > +An I/O error was encountered while performing the query.
> > +.TP
> > +.B ENOMEM
> > +There was insufficient memory to perform the query.
> > +.TP
> > +.B EPERM
> > +Caller did not have permission to change the attributes.
> > +.SH CONFORMING TO
> > +This API is implemented by the ext4, xfs, btrfs, and f2fs filesystems on the
> > +Linux kernel.
> > +Not all fields may be understood by filesystems other than xfs.
> > +.SH SEE ALSO
> > +.BR ioctl (2)
> > diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> > index 462ccbd8..2992b5be 100644
> > --- a/man/man3/xfsctl.3
> > +++ b/man/man3/xfsctl.3
> > @@ -132,161 +132,17 @@ will fail with EINVAL.
> >  All I/O requests are kept consistent with any data brought into
> >  the cache with an access through a non-direct I/O file descriptor.
> >  
> > -.TP
> > -.B XFS_IOC_FSGETXATTR
> > -Get additional attributes associated with files in XFS file systems.
> > -The final argument points to a variable of type
> > -.BR "struct fsxattr" ,
> > -whose fields include:
> > -.B fsx_xflags
> > -(extended flag bits),
> > -.B fsx_extsize
> > -(nominal extent size in file system blocks),
> > -.B fsx_nextents
> > -(number of data extents in the file).
> > -A
> > -.B fsx_extsize
> > -value returned indicates that a preferred extent size was previously
> > -set on the file, a
> > -.B fsx_extsize
> > -of zero indicates that the defaults for that filesystem will be used.
> > -A
> > -.B fsx_cowextsize
> > -value returned indicates that a preferred copy on write extent size was
> > -previously set on the file, whereas a
> > -.B fsx_cowextsize
> > -of zero indicates that the defaults for that filesystem will be used.
> > -The current default for
> > -.B fsx_cowextsize
> > -is 128 blocks.
> > -Currently the meaningful bits for the
> > -.B fsx_xflags
> > -field are:
> > -.PD 0
> > -.RS
> > -.TP 1.0i
> > -.SM "Bit 0 (0x1) \- XFS_XFLAG_REALTIME"
> > -The file is a realtime file.
> > -.TP
> > -.SM "Bit 1 (0x2) \- XFS_XFLAG_PREALLOC"
> > -The file has preallocated space.
> > -.TP
> > -.SM "Bit 3 (0x8) \- XFS_XFLAG_IMMUTABLE"
> > -The file is immutable - it cannot be modified, deleted or renamed,
> > -no link can be created to this file and no data can be written to the
> > -file.
> > -Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
> > -capability can set or clear this flag.
> > -.TP
> > -.SM "Bit 4 (0x10) \- XFS_XFLAG_APPEND"
> > -The file is append-only - it can only be open in append mode for
> > -writing.
> > -Only the superuser or a process possessing the CAP_LINUX_IMMUTABLE
> > -capability can set or clear this flag.
> > -.TP
> > -.SM "Bit 5 (0x20) \- XFS_XFLAG_SYNC"
> > -All writes to the file are synchronous.
> > -.TP
> > -.SM "Bit 6 (0x40) \- XFS_XFLAG_NOATIME"
> > -When the file is accessed, its atime record is not modified.
> > -.TP
> > -.SM "Bit 7 (0x80) \- XFS_XFLAG_NODUMP"
> > -The file should be skipped by backup utilities.
> > -.TP
> > -.SM "Bit 8 (0x100) \- XFS_XFLAG_RTINHERIT"
> > -Realtime inheritance bit - new files created in the directory
> > -will be automatically realtime, and new directories created in
> > -the directory will inherit the inheritance bit.
> > -.TP
> > -.SM "Bit 9 (0x200) \- XFS_XFLAG_PROJINHERIT"
> > -Project inheritance bit - new files and directories created in
> > -the directory will inherit the parents project ID.  New
> > -directories also inherit the project inheritance bit.
> > -.TP
> > -.SM "Bit 10 (0x400) \- XFS_XFLAG_NOSYMLINKS"
> > -Can only be set on a directory and disallows creation of
> > -symbolic links in that directory.
> > -.TP
> > -.SM "Bit 11 (0x800) \- XFS_XFLAG_EXTSIZE"
> > -Extent size bit - if a basic extent size value is set on the file
> > -then the allocator will allocate in multiples of the set size for
> > -this file (see
> > -.B XFS_IOC_FSSETXATTR
> > -below).
> > -.TP
> > -.SM "Bit 12 (0x1000) \- XFS_XFLAG_EXTSZINHERIT"
> > -Extent size inheritance bit - new files and directories created in
> > -the directory will inherit the parents basic extent size value (see
> > -.B XFS_IOC_FSSETXATTR
> > -below).
> > -Can only be set on a directory.
> > -.TP
> > -.SM "Bit 13 (0x2000) \- XFS_XFLAG_NODEFRAG"
> > -No defragment file bit - the file should be skipped during a defragmentation
> > -operation. When applied to a directory, new files and directories created will
> > -inherit the no\-defrag bit.
> > -.TP
> > -.SM "Bit 14 (0x4000) \- XFS_XFLAG_FILESTREAM"
> > -Filestream allocator bit - allows a directory to reserve an allocation
> > -group for exclusive use by files created within that directory. Files
> > -being written in other directories will not use the same allocation
> > -group and so files within different directories will not interleave
> > -extents on disk. The reservation is only active while files are being
> > -created and written into the directory.
> > -.TP
> > -.SM "Bit 15 (0x8000) \- XFS_XFLAG_DAX"
> > -If the filesystem lives on directly accessible persistent memory, reads and
> > -writes to this file will go straight to the persistent memory, bypassing the
> > -page cache.
> > -A file cannot be reflinked and have the
> > -.BR XFS_XFLAG_DAX
> > -set at the same time.
> > -That is to say that DAX files cannot share blocks.
> > -.TP
> > -.SM "Bit 16 (0x10000) \- XFS_XFLAG_COWEXTSIZE"
> > -Copy on Write Extent size bit - if a CoW extent size value is set on the file,
> > -the allocator will allocate extents for staging a copy on write operation
> > -in multiples of the set size for this file (see
> > -.B XFS_IOC_FSSETXATTR
> > -below).
> > -If the CoW extent size is set on a directory, then new file and directories
> > -created in the directory will inherit the parent's CoW extent size value.
> > -.TP
> > -.SM "Bit 31 (0x80000000) \- XFS_XFLAG_HASATTR"
> > -The file has extended attributes associated with it.
> > -.RE
> >  .PP
> > -.PD
> > -
> > -.TP
> > -.B XFS_IOC_FSGETXATTRA
> > -Identical to
> > +.nf
> >  .B XFS_IOC_FSGETXATTR
> > -except that the
> > -.B fsx_nextents
> > -field contains the number of attribute extents in the file.
> > -
> > +.B XFS_IOC_FSGETXATTRA
> > +.fi
> > +.PD 0
> >  .TP
> >  .B XFS_IOC_FSSETXATTR
> > -Set additional attributes associated with files in XFS file systems.
> > -The final argument points to a variable of type
> > -.BR "struct fsxattr" ,
> > -but only the following fields are used in this call:
> > -.BR fsx_xflags ,
> > -.BR fsx_extsize ,
> > -.BR fsx_cowextsize ,
> > -and
> > -.BR fsx_projid .
> > -The
> > -.B fsx_xflags
> > -realtime file bit and the file's extent size may be changed only
> > -when the file is empty, except in the case of a directory where
> > -the extent size can be set at any time (this value is only used
> > -for regular file allocations, so should only be set on a directory
> > -in conjunction with the XFS_XFLAG_EXTSZINHERIT flag).
> > -The copy on write extent size,
> > -.BR fsx_cowextsize ,
> > -can be set at any time.
> > +See
> > +.BR ioctl_xfs_fsgetxattr (2)
> > +for more information.
> >  
> >  .TP
> >  .B XFS_IOC_GETBMAP
> > @@ -649,6 +505,7 @@ The remainder of these operations will not be described further
> >  as they are not of general use to applications.
> >  
> >  .SH SEE ALSO
> > +.BR ioctl_xfs_fsgetxattr (2),
> >  .BR fstatfs (2),
> >  .BR statfs (2),
> >  .BR xfs (5),
> > 

Re: [PATCH 2/9] libxfs: break out the fsop geometry manpage

[Darrick J. Wong]

On Fri, Jun 14, 2019 at 05:00:30PM -0500, Eric Sandeen wrote:
> On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> > 
> > Break out the fs geometry ioctl into a separate manpage so that we can
> > document how it works.
> > 
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> >  man/man2/ioctl_xfs_fsop_geometry.2 |  214 ++++++++++++++++++++++++++++++++++++
> >  man/man3/xfsctl.3                  |   11 +-
> >  2 files changed, 221 insertions(+), 4 deletions(-)
> >  create mode 100644 man/man2/ioctl_xfs_fsop_geometry.2
> > 
> > 
> > diff --git a/man/man2/ioctl_xfs_fsop_geometry.2 b/man/man2/ioctl_xfs_fsop_geometry.2
> > new file mode 100644
> > index 00000000..4045e03b
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_fsop_geometry.2
> > @@ -0,0 +1,214 @@
> > +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> > +.\"
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-FSOP-GEOMETRY 2 2019-04-11 "XFS"
> > +.SH NAME
> > +ioctl_xfs_fsop_geometry \- report XFS filesystem shape
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <xfs/xfs_fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSOP_GEOMETRY, struct xfs_fsop_geometry *" arg );
> > +.PP
> 
> ditto on the .br?
> 
> also xfs_fsop_geometry isn't a thing, is it?  xfs_fsop_geom?
> 
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSOP_GEOMETRY_V1, struct xfs_fsop_geometry_v1 *" arg );
> 
> and xfs_fsop_geom_v1

Fixed.

> > +.SH DESCRIPTION
> > +Report the storage space parameters that influence allocation decisions in
> > +this XFS filesystem.
> > +This information is conveyed in a structure of the following form:
> > +.PP
> > +.in +4n
> > +.nf
> > +struct xfs_fsop_geom {
> > +	__u32         blocksize;
> > +	__u32         rtextsize;
> > +	__u32         agblocks;
> > +	__u32         agcount;
> > +	__u32         logblocks;
> > +	__u32         sectsize;
> > +	__u32         inodesize;
> > +	__u32         imaxpct;
> > +	__u64         datablocks;
> > +	__u64         rtblocks;
> > +	__u64         rtextents;
> > +	__u64         logstart;
> > +	unsigned char uuid[16];
> > +	__u32         sunit;
> > +	__u32         swidth;
> > +	__s32         version;
> > +	__u32         flags;
> > +	__u32         logsectsize;
> > +	__u32         rtsectsize;
> > +	__u32         dirblocksize;
> > +	/* struct xfs_fsop_geom_v1 stops here. */
> > +
> > +	__u32         logsunit;
> > +};
> > +.fi
> > +.in
> > +.PP
> > +.I blocksize
> > +is the size of a fundamental filesystem block, in bytes.
> > +.PP
> > +.I rtextsize
> > +is the size of an extent on the realtime volume, in bytes.
> > +.PP
> > +.I agblocks
> > +is the size of an allocation group, in units of filesystem blocks.
> > +.PP
> > +.I agcount
> > +is the number of allocation groups in the filesystem.
> > +.PP
> > +.I logblocks
> > +is the size of the log, in units of filesystem blocks.
> > +.PP
> > +.I sectsize
> > +is the smallest amount of data that can be written to the data device
> > +atomically, in bytes.
> > +.PP
> > +.I inodesize
> > +is the size of an inode record, in bytes.
> > +.PP
> > +.I imaxpct
> > +is the maximum percentage of the filesystem that can be allocated to inode
> > +record blocks.
> > +.PP
> > +.I datablocks
> > +is the size of the data device, in units of filesystem blocks.
> > +.PP
> > +.I rtblocks
> > +is the size of the realtime device, in units of filesystem blocks.
> > +.PP
> > +.I rtextents
> > +is the number of extents that can be allocated on the realtime device.
> > +This ought to be
> > +.RB "( " rtblocks " * " blocksize " ) / " rtextsize .
> 
> ought to be?  I'm not sure what that means?

Dropped.

> > +.PP
> > +.I logstart
> > +tells the start of the log, in units of filesystem blocks.
> 
> contains?

I'll change it to 'is' here.

> > +If the filesystem has an external log, this will be zero.
> > +.PP
> > +.I uuid
> > +is the universal unique identifier of the filesystem.
> > +.PP
> > +.I sunit
> > +is what the filesystem has been told is the size of a RAID stripe unit on the
> > +underlying data device, in filesystem blocks.
> > +.PP
> > +.I swidth
> > +is what the filesystem has been told is the width of a RAID stripe on the
> > +underlying data device, in units of RAID stripe units.
> > +.PP
> > +.I version
> > +is the version of this structure.
> > +This value will be XFS_FSOP_GEOM_VERSION.
> > +.PP
> > +.I flags
> > +tell us what features are enabled on the filesystem.
> > +This field can be any combination of the following:
> > +.RS 0.4i
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_ATTR
> > +Extended attributes are present.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_NLINK
> > +This filesystem supports up to 2^32 links.
> 
> and if not it supports what?
> 
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_QUOTA
> > +Quotas are enabled.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_IALIGN
> > +Inodes are aligned for better performance.
> 
> aligned to ____ ? (worth trying to explain?)

Aligned to ... inode cluster buffer size, which we've never really
documented outside of "RTFS"? :)

> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_DALIGN
> > +Data blocks are aligned for better performance.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_SHARED
> > +Unused.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_EXTFLG
> > +Filesystem supports unwritten extents.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_DIRV2
> > +Directories maintain free space data for better performance.
> 
> I don't remember all the v1->v2 differences but in other places
> you simply say "contains version 2 format" or whatnot, so that might
> suffice here.  Also can't do v1 since forever, anyway.  ;)

Fixed.

> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_LOGV2
> > +Log uses the V2 format.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_SECTOR
> > +The log device has a sector size larger than 512 bytes.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_ATTR2
> > +Filesystem contains V2 extended attributes.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_PROJID32
> > +Project IDs can be as large as 2^32.
> 
> otherwise 2^16?


yes.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_DIRV2CI
> > +Case-insensitive lookups are supported on directories.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_LAZYSB
> > +On-disk superblock counters are updated only at unmount time.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_V5SB
> > +Metadata blocks are self describing and contain checksums.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_FTYPE
> > +Directories cache inode types in directory entries.
> 
> s/cache/contain/

Ok.

> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_FINOBT
> > +Filesystem maintains an index of free inodes.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_SPINODES
> > +Filesystem tries harder to allocate inodes when free space is fragmented.
> 
> Filesystem may allocate discontinuous inode chunks when free space is fragmented?

Ok.

> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_RMAPBT
> > +Filesystem stores reverse mappings of blocks to owners.
> > +.TP
> > +.B XFS_FSOP_GEOM_FLAGS_REFLINK
> > +Filesystem supports sharing blocks.
> 
> between inodes?

Between files; will fix.

> > +.RE
> > +
> > +.PD 1
> > +.PP
> > +.I logsectsize
> > +is the smallest amount of data that can be written to the log device atomically,
> > +in bytes.
> 
> oh hello, we're back to the structure members again!
> 
> I wonder if it'd be better to move the flag details down below all the structure descriptions.

Yeah, probably.  I'll do that for all the new manpages since otherwise
this becomes a mess.

--D

> > +.PP
> > +.I rtsectsize
> > +is the smallest amount of data that can be written to the realtime device
> > +atomically, in bytes.
> > +.PP
> > +.I dirblocksize
> > +is the size of directory blocks, in bytes.
> > +.PP
> > +.I logsunit
> > +is what the filesystem has been told is the size of a RAID stripe unit on the
> > +underlying log device, in filesystem blocks.
> > +This field is meaningful only if the flag
> > +.B  XFS_FSOP_GEOM_FLAGS_LOGV2
> > +is set.
> > +.SH RETURN VALUE
> > +On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error.
> > +.PP
> > +.SH ERRORS
> > +Error codes can be one of, but are not limited to, the following:
> > +.TP
> > +.B EFAULT
> > +The kernel was not able to copy into the userspace buffer.
> > +.TP
> > +.B EFSBADCRC
> > +Metadata checksum validation failed while performing the query.
> > +.TP
> > +.B EFSCORRUPTED
> > +Metadata corruption was encountered while performing the query.
> > +.TP
> > +.B EIO
> > +An I/O error was encountered while performing the query.
> > +.SH CONFORMING TO
> > +This API is specific to XFS filesystem on the Linux kernel.
> > +.SH SEE ALSO
> > +.BR ioctl (2)
> > diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> > index 2992b5be..1237eac6 100644
> > --- a/man/man3/xfsctl.3
> > +++ b/man/man3/xfsctl.3
> > @@ -479,6 +479,12 @@ the kernel, except no output count parameter is used (should
> >  be initialized to zero).
> >  An error is returned if the inode number is invalid.
> >  
> > +.TP
> > +.B XFS_IOC_FSGEOMETRY
> > +See
> > +.BR ioctl_xfs_fsop_geometry (2)
> > +for more information.
> > +
> >  .PP
> >  .nf
> >  .B XFS_IOC_THAW
> > @@ -494,10 +500,6 @@ An error is returned if the inode number is invalid.
> >  These interfaces are used to implement various filesystem internal
> >  operations on XFS filesystems.
> >  For
> > -.B XFS_IOC_FSGEOMETRY
> > -(get filesystem mkfs time information), the output structure is of type
> > -.BR struct xfs_fsop_geom .
> > -For
> >  .B XFS_FS_COUNTS
> >  (get filesystem dynamic global information), the output structure is of type
> >  .BR xfs_fsop_counts_t .
> > @@ -506,6 +508,7 @@ as they are not of general use to applications.
> >  
> >  .SH SEE ALSO
> >  .BR ioctl_xfs_fsgetxattr (2),
> > +.BR ioctl_xfs_fsop_geometry (2),
> >  .BR fstatfs (2),
> >  .BR statfs (2),
> >  .BR xfs (5),
> > 

Re: [PATCH 3/9] libxfs: break out the bulkstat manpage

[Darrick J. Wong]

On Fri, Jun 14, 2019 at 06:02:03PM -0500, Eric Sandeen wrote:
> On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> > 
> > Break out the bulkstat ioctl into a separate manpage so that we can
> > document how it works.
> > 
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> >  man/man2/ioctl_xfs_fsbulkstat.2 |  212 +++++++++++++++++++++++++++++++++++++++
> >  man/man3/xfsctl.3               |   87 +---------------
> >  2 files changed, 219 insertions(+), 80 deletions(-)
> >  create mode 100644 man/man2/ioctl_xfs_fsbulkstat.2
> > 
> > 
> > diff --git a/man/man2/ioctl_xfs_fsbulkstat.2 b/man/man2/ioctl_xfs_fsbulkstat.2
> > new file mode 100644
> > index 00000000..8908631a
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_fsbulkstat.2
> > @@ -0,0 +1,212 @@
> > +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> > +.\"
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-FSBULKSTAT 2 2019-04-11 "XFS"
> > +.SH NAME
> > +ioctl_xfs_fsbulkstat \- query information for a batch of XFS inodes
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <xfs/xfs_fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSBULKSTAT, struct xfs_fsop_bulkreq *" arg );
> > +.PP
> 
> .br   *shrug* maybe not, seems like you have a plan here ;)

Fixed.
> 
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSBULKSTAT_SINGLE, struct xfs_fsop_bulkreq *" arg );
> > +.SH DESCRIPTION
> > +Query stat information for a bunch of XFS inodes.
> 
> s/bunch/group/ or s/a bunch of//

Fixed.

> 
> > +These ioctls use
> > +.B struct xfs_fsop_bulkreq
> > +to set up a bulk transfer with the kernel:
> > +.PP
> > +.in +4n
> > +.nf
> > +struct xfs_fsop_bulkreq {
> > +	__u64             *lastip;
> > +	__s32             count;
> > +	void              *ubuffer;
> > +	__s32             *ocount;
> > +};
> > +.fi
> > +.in
> > +.PP
> > +.I lastip
> > +points to a value that will receive the number of the "last inode".
> 
> can it be NULL?

Yes; fixed.

> > +For
> > +.BR FSBULKSTAT ,
> > +this should be set to one less than the number of the first inode for which the
> > +caller wants information, or zero to start with the first inode in the
> > +filesystem.
> > +For
> > +.BR FSBULKSTAT_SINGLE ,
> > +this should be set to the number of the inode for which the caller wants
> > +information.
> > +After the call, this value will be set to the number of the last inode for
> > +which information was supplied.
> > +This field will not be updated if
> > +.I ocount
> > +is NULL.
> > +.PP
> > +.I count
> > +is the number of inodes to examine.
> 
> and the size of the area pointed to by *ubuffer?
> (I guess that's covered in the *ubuffer description)

I'll reiterate it.

> > +This value must be set to 1 for
> > +.BR FSBULKSTAT_SINGLE .
> > +.PP
> > +.I ocount
> > +points to a value that will receive the number of records returned.
> > +If this value is NULL, then neither
> > +.I ocount
> > +nor
> > +.I lastip
> > +will be updated.
> > +.PP
> > +.I ubuffer
> > +points to a memory buffer where information will be copied.
> 
> into which inode information will be copied?

Fixed.

> > +This buffer must be an array of
> > +.B struct xfs_bstat
> > +which is described below.
> > +The array must have at least
> > +.I count
> > +elements.
> > +.PP
> > +.in +4n
> > +.nf
> > +struct xfs_bstat {
> > +	__u64             bs_ino;
> > +	__u16             bs_mode;
> > +	__u16             bs_nlink;
> > +	__u32             bs_uid;
> > +	__u32             bs_gid;
> > +	__u32             bs_rdev;
> > +	__s32             bs_blksize;
> > +	__s64             bs_size;
> > +	struct xfs_bstime bs_atime;
> > +	struct xfs_bstime bs_mtime;
> > +	struct xfs_bstime bs_ctime;
> > +	int64_t           bs_blocks;
> > +	__u32             bs_xflags;
> > +	__s32             bs_extsize;
> > +	__s32             bs_extents;
> > +	__u32             bs_gen;
> > +	__u16             bs_projid_lo;
> > +	__u16             bs_forkoff;
> > +	__u16             bs_projid_hi;
> > +	unsigned char     bs_pad[6];
> > +	__u32             bs_cowextsize;
> > +	__u32             bs_dmevmask;
> > +	__u16             bs_dmstate;
> > +	__u16             bs_aextents;
> > +};
> > +.fi
> > +.in
> > +.PP
> 
> The structure members are as follows:

Ok.

> > +.I bs_ino
> > +is the number of this inode record.
> 
> is the inode number for this record

Ok.

> > +.PP
> > +.I bs_mode
> > +is the file type and mode.
> > +.PP
> > +.I bs_nlink
> > +is the number of hard links to this inode.
> > +.PP
> > +.I bs_uid
> > +is the user id.
> > +.PP
> > +.I bs_gid
> > +is the group id.
> > +.PP
> > +.I bs_rdev
> > +is the encoded device id if this is a special file.
> > +.PP
> > +.I bs_blksize
> > +is the size of a data block for this file, in units of bytes.
> > +.PP
> > +.I bs_size
> > +is the size of the file, in bytes.
> > +.PP
> > +.I bs_atime
> > +is the last time this file was accessed.
> > +.PP
> > +.I bs_mtime
> > +is the last time the contents of this file were modified.
> > +.PP
> > +.I bs_ctime
> > +is the last time this inode record was modified.
> > +.PP
> > +.I bs_blocks
> > +is the number of filesystem blocks allocated to this file, including metadata.
> > +.PP
> > +.I bs_xflags
> > +tell us what extended flags are set this inode.
> 
> contains the extended flags which are set in this inode
> 
> > +These flags are the same values as those set in the
> > +.I fsx_xflags
> > +field of
> > +.BR "struct fsxattr" ;
> > +please see the
> > +.BR ioctl_fsgetxattr (2)
> > +manpage for more information.
> 
> I dig it but you made an ioctl_xfs_fsgetxattr(2) manpage...

Fixed.

> (I forget, how do we alias manpages?)
> 
> also this should go in SEE ALSO

Fixed.

> > +
> > +.PD 1
> > +.PP
> > +.I bs_extsize
> > +is the extent size hint for this file, in bytes.
> > +.PP
> > +.I bs_extents
> > +is the number of storage space extents associated with this file's data.
> 
> storage space extents sounds odd...
> 
> is the number of data extents in this file.

"storage mappings" instead of "data extents"?

> > +.PP
> > +.I bs_gen
> > +is the generation number of the inode record.
> > +.PP
> > +.I bs_projid_lo
> > +is the lower 16-bits of the project id.
> > +.PP
> > +.I bs_forkoff
> > +is the offset of the attribute fork in the inode record, in bytes.
> > +.PP
> > +.I bs_projid_hi
> > +is the upper 16-bits of the project id.
> > +.PP
> > +.I bs_pad[6]
> > +is zeroed.
> > +.PP
> > +.I bs_cowextsize
> > +is the Copy on Write extent size hint for this file, in bytes.
> > +.PP
> > +.I bs_dmevmask
> > +is unused on Linux.
> > +.PP
> > +.I bs_dmstate
> > +is unused on Linux.
> > +.PP
> > +.I bs_aextents
> > +is the number of storage space extents associated with this file's extended
> > +attributes.
> 
> is the number of extended attribute extents in this file?  *shrug*

"...the number of storage mappings associated with the extended attributes..." ?

--D

> > +.SH RETURN VALUE
> > +On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error.
> > +.PP
> > +.SH ERRORS
> > +Error codes can be one of, but are not limited to, the following:
> > +.TP
> > +.B EFAULT
> > +The kernel was not able to copy into the userspace buffer.
> > +.TP
> > +.B EFSBADCRC
> > +Metadata checksum validation failed while performing the query.
> > +.TP
> > +.B EFSCORRUPTED
> > +Metadata corruption was encountered while performing the query.
> > +.TP
> > +.B EINVAL
> > +One of the arguments was not valid.
> > +.TP
> > +.B EIO
> > +An I/O error was encountered while performing the query.
> > +.TP
> > +.B ENOMEM
> > +There was insufficient memory to perform the query.
> > +.SH CONFORMING TO
> > +This API is specific to XFS filesystem on the Linux kernel.
> > +.SH SEE ALSO
> > +.BR ioctl (2)
> > diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> > index 1237eac6..94a6ad4b 100644
> > --- a/man/man3/xfsctl.3
> > +++ b/man/man3/xfsctl.3
> > @@ -399,92 +399,18 @@ An output
> >  .B ocount
> >  value of zero means that the inode table has been exhausted.
> >  
> > -.TP
> > -.B XFS_IOC_FSBULKSTAT
> > -This interface is used to extract inode information (stat
> > -information) "in bulk" from a filesystem.  It is intended to
> > -be called iteratively, to obtain information about the entire
> > -set of inodes in a filesystem.
> > -The information is passed in and out via a structure of type
> > -.B xfs_fsop_bulkreq_t
> > -pointed to by the final argument.
> > -.B lastip
> > -is a pointer to a variable containing the last inode number returned,
> > -initially it should be zero.
> > -.B icount
> > -indicates the size of the array of structures specified by
> > -.B ubuffer.
> > -.B ubuffer
> > -is the address of an array of structures of type
> > -.BR xfs_bstat_t .
> > -Many of the elements in the structure are the same as for the stat
> > -structure.
> > -The structure has the following elements:
> > -.B bs_ino
> > -(inode number),
> > -.B bs_mode
> > -(type and mode),
> > -.B bs_nlink
> > -(number of links),
> > -.B bs_uid
> > -(user id),
> > -.B bs_gid
> > -(group id),
> > -.B bs_rdev
> > -(device value),
> > -.B bs_blksize
> > -(block size of the filesystem),
> > -.B bs_size
> > -(file size in bytes),
> > -.B bs_atime
> > -(access time),
> > -.B bs_mtime
> > -(modify time),
> > -.B bs_ctime
> > -(inode change time),
> > -.B bs_blocks
> > -(number of blocks used by the file),
> > -.B bs_xflags
> > -(extended flags),
> > -.B bs_extsize
> > -(extent size),
> > -.B bs_extents
> > -(number of extents),
> > -.B bs_gen
> > -(generation count),
> > -.B bs_projid_lo
> > -(project id - low word),
> > -.B bs_projid_hi
> > -(project id - high word, used when projid32bit feature is enabled),
> > -.B bs_dmevmask
> > -(DMIG event mask),
> > -.B bs_dmstate
> > -(DMIG state information), and
> > -.B bs_aextents
> > -(attribute extent count).
> > -.B ocount
> > -is a pointer to a count of returned values, filled in by the call.
> > -An output
> > -.B ocount
> > -value of zero means that the inode table has been exhausted.
> > -
> > -.TP
> > -.B XFS_IOC_FSBULKSTAT_SINGLE
> > -This interface is a variant of the
> > -.B XFS_IOC_FSBULKSTAT
> > -interface, used to obtain information about a single inode.
> > -for an open file in the filesystem of interest.
> > -The same structure is used to pass information in and out of
> > -the kernel, except no output count parameter is used (should
> > -be initialized to zero).
> > -An error is returned if the inode number is invalid.
> > -
> >  .TP
> >  .B XFS_IOC_FSGEOMETRY
> >  See
> >  .BR ioctl_xfs_fsop_geometry (2)
> >  for more information.
> >  
> > +.TP
> > +.BR XFS_IOC_FSBULKSTAT " or " XFS_IOC_FSBULKSTAT_SINGLE
> > +See
> > +.BR ioctl_xfs_fsbulkstat (2)
> > +for more information.
> > +
> >  .PP
> >  .nf
> >  .B XFS_IOC_THAW
> > @@ -509,6 +435,7 @@ as they are not of general use to applications.
> >  .SH SEE ALSO
> >  .BR ioctl_xfs_fsgetxattr (2),
> >  .BR ioctl_xfs_fsop_geometry (2),
> > +.BR ioctl_xfs_fsbulkstat (2),
> >  .BR fstatfs (2),
> >  .BR statfs (2),
> >  .BR xfs (5),
> > 

Re: [PATCH 5/9] libxfs: break out the INUMBERS manpage

[Darrick J. Wong]

On Mon, Jun 17, 2019 at 11:34:00AM -0500, Eric Sandeen wrote:
> 
> 
> On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> > 
> > Create a separate manual page for the INUMBERS ioctl so we can document
> > how it works.
> > 
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> >  man/man2/ioctl_xfs_fsinumbers.2 |  115 +++++++++++++++++++++++++++++++++++++++
> >  man/man3/xfsctl.3               |   34 +-----------
> >  2 files changed, 119 insertions(+), 30 deletions(-)
> >  create mode 100644 man/man2/ioctl_xfs_fsinumbers.2
> > 
> > 
> > diff --git a/man/man2/ioctl_xfs_fsinumbers.2 b/man/man2/ioctl_xfs_fsinumbers.2
> > new file mode 100644
> > index 00000000..86cdf4d9
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_fsinumbers.2
> > @@ -0,0 +1,115 @@
> > +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> > +.\"
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-FSINUMBERS 2 2019-04-16 "XFS"
> > +.SH NAME
> > +ioctl_xfs_fsinumbers \- extract a list of valid inode numbers from an XFS filesystem
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <xfs/xfs_fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSINUMBERS, struct xfs_fsop_bulkreq *" arg );
> > +.SH DESCRIPTION
> > +Query a list of valid inode numbers from an XFS filesystem.
> > +It is intended to be called iteratively to obtain the entire set of inodes.
> > +These ioctls use
> > +.B struct xfs_fsop_bulkreq
> > +to set up a bulk transfer with the kernel:
> > +.PP
> > +.in +4n
> > +.nf
> > +struct xfs_fsop_bulkreq {
> > +	__u64   *lastip;
> > +	__s32   count;
> > +	void    *ubuffer;
> > +	__s32   *ocount;
> > +};
> > +.fi
> > +.in
> > +.PP
> > +.I lastip
> > +points to a value that will receive the number of the "last inode".
> > +This should be set to one less than the number of the first inode for which the
> > +caller wants information, or zero to start with the first inode in the
> > +filesystem.
> > +After the call, this value will be set to the number of the last inode for
> > +which information is supplied.
> > +This field will not be updated if
> > +.I ocount
> > +is NULL.
> > +.PP
> > +.I count
> > +is the number of inodes to examine.
> 
> again should it have something like "corresponding to the number
> of array elements passed in in the ubuffer array?"

Fixed.

> > +.PP
> > +.I ocount
> > +points to a value that will receive the number of records returned.
> > +An output value of zero means that there are no more inodes left to enumerate.
> > +If this value is NULL, then neither
> > +.I ocount
> > +nor
> > +.I lastip
> > +will be updated.
> > +.PP
> > +.I ubuffer
> > +points to a memory buffer where information will be copied.
> > +This buffer must be an array of
> > +.B struct xfs_inogrp
> > +which is described below.
> > +The array must have at least
> > +.I count
> > +elements.
> > +.PP
> > +.in +4n
> > +.nf
> > +struct xfs_inogrp {
> > +	__u64   xi_startino;
> > +	__s32   xi_alloccount;
> > +	__u64   xi_allocmask;
> > +}
> > +.fi
> > +.in
> > +.PP
> > +.I xi_startino
> > +is the number of this inode numbers record.
> 
> this phrasing confuses me.
> 
> xi_startino is the first inode number in this inode... group?

Yes, will chnage it to that.

> > +Each inode numbers record will correspond roughly to a record in the inode
> > +btree, though this is not guaranteed.
> 
> I don't think that is useful information.

Ok.

> > +.PP
> > +.I xi_alloccount
> > +is the number of bits that are set in
> > +.IR xi_allocmask .
> 
> i.e. the number of inodes in use in this group?

Yes.  I'll add a second sentence stating this.

> > +.PP
> > +.I xi_allocmask
> > +is the mask of inodes that are in use for this inode.
> 
> inodes that are in use for this inode?  wut.

Yeah, is dumb.

"is a bitmask of inodes that are allocated in this inode group."

> > +The bitmask is 64 bits long, and the least significant bit corresponds to inode
> > +.BR xi_startino .
> 
> ok so finally we get to what I consider to be the useful thing that ties it
> all together ;)
> 
> so maybe best to just say that it returns inode usage information for a group of
> 64 consecutive inode numbers, starting with inode xi_startino, with a bitmask of
> in-use inodes in xi_allocmask, with total in-use inodes for this batch/group/set
> shown in xi_alloccount?

Yep.  I'll try to clarify this more in the manpage.

--D

> 
> > +.SH RETURN VALUE
> > +On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error.
> > +.PP
> > +.SH ERRORS
> > +Error codes can be one of, but are not limited to, the following:
> > +.TP
> > +.B EFAULT
> > +The kernel was not able to copy into the userspace buffer.
> > +.TP
> > +.B EFSBADCRC
> > +Metadata checksum validation failed while performing the query.
> > +.TP
> > +.B EFSCORRUPTED
> > +Metadata corruption was encountered while performing the query.
> > +.TP
> > +.B EINVAL
> > +One of the arguments was not valid.
> > +.TP
> > +.B EIO
> > +An I/O error was encountered while performing the query.
> > +.TP
> > +.B ENOMEM
> > +There was insufficient memory to perform the query.
> > +.SH CONFORMING TO
> > +This API is specific to XFS filesystem on the Linux kernel.
> > +.SH SEE ALSO
> > +.BR ioctl (2)
> > diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> > index cdf0fcfc..148119a9 100644
> > --- a/man/man3/xfsctl.3
> > +++ b/man/man3/xfsctl.3
> > @@ -368,36 +368,9 @@ can be any open file in the XFS filesystem in question.
> >  .PP
> >  .TP
> >  .B XFS_IOC_FSINUMBERS
> > -This interface is used to extract a list of valid inode numbers from an
> > -XFS filesystem.
> > -It is intended to be called iteratively, to obtain the entire set of inodes.
> > -The information is passed in and out via a structure of type
> > -.B xfs_fsop_bulkreq_t
> > -pointed to by the final argument.
> > -.B lastip
> > -is a pointer to a variable containing the last inode number returned,
> > -initially it should be zero.
> > -.B icount
> > -is the size of the array of structures specified by
> > -.BR ubuffer .
> > -.B ubuffer
> > -is the address of an array of structures, of type
> > -.BR xfs_inogrp_t .
> > -This structure has the following elements:
> > -.B xi_startino
> > -(starting inode number),
> > -.B xi_alloccount
> > -(count of bits set in xi_allocmask), and
> > -.B xi_allocmask
> > -(mask of allocated inodes in this group).
> > -The bitmask is 64 bits long, and the least significant bit corresponds to inode
> > -.B xi_startino.
> > -Each bit is set if the corresponding inode is in use.
> > -.B ocount
> > -is a pointer to a count of returned values, filled in by the call.
> > -An output
> > -.B ocount
> > -value of zero means that the inode table has been exhausted.
> > +See
> > +.BR ioctl_xfs_fsinumbers (2)
> > +for more information.
> >  
> >  .TP
> >  .B XFS_IOC_FSGEOMETRY
> > @@ -442,6 +415,7 @@ as they are not of general use to applications.
> >  .BR ioctl_xfs_fsgetxattr (2),
> >  .BR ioctl_xfs_fsop_geometry (2),
> >  .BR ioctl_xfs_fsbulkstat (2),
> > +.BR ioctl_xfs_fsinumbers (2),
> >  .BR fstatfs (2),
> >  .BR statfs (2),
> >  .BR xfs (5),
> > 

Re: [PATCH 6/9] libxfs: break out FSCOUNTS manpage

[Darrick J. Wong]

On Mon, Jun 17, 2019 at 12:12:42PM -0500, Eric Sandeen wrote:
> On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> > 
> > Create a separate manual page for the FSCOUNTS ioctl so we can document
> > how it works.
> > 
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> >  man/man2/ioctl_xfs_fscounts.2 |   67 +++++++++++++++++++++++++++++++++++++++++
> >  man/man3/xfsctl.3             |   14 +++++----
> >  2 files changed, 75 insertions(+), 6 deletions(-)
> >  create mode 100644 man/man2/ioctl_xfs_fscounts.2
> > 
> > 
> > diff --git a/man/man2/ioctl_xfs_fscounts.2 b/man/man2/ioctl_xfs_fscounts.2
> > new file mode 100644
> > index 00000000..44b214a1
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_fscounts.2
> > @@ -0,0 +1,67 @@
> > +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> > +.\"
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-FSCOUNTS 2 2019-04-16 "XFS"
> > +.SH NAME
> > +ioctl_xfs_fscounts \- query XFS summary counter information
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <xfs/xfs_fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_FSCOUNTS, struct xfs_fsop_counts *" arg );
> > +.SH DESCRIPTION
> > +Query the raw filesystem summary counters.
> > +Unlike
> > +.BR statvfs (3),
> > +the values returned here are the raw values, which do not reflect any
> > +alterations or limits set by quotas.
> 
> it's altered by /project/ quotas specifically, right?  Should that be
> made clear?  Or is it more than just project?

It's only project quotas; will clarify.

> 
> > +The counter information is conveyed in a structure of the following form:
> > +.PP
> > +.in +4n
> > +.nf
> > +struct xfs_fscounts {
> 
> xfs_fsop_counts?
> 
> (this is the second time there's a misnamed structure (I think?)
> so I feel like double checking them all is in order unless i'm
> missing something?)

Massive thinko on my part, I guess?

> > +	__u64   freedata;
> > +	__u64   freertx;
> > +	__u64   freeino;
> > +	__u64   allocino;
> > +};
> > +.fi
> > +.in
> > +.PP
> > +.I freedata
> > +is the number of free filesystem blocks on the data device.
> > +.PP
> > +.I freertx
> > +is the number of free xtents on the realtime device.
> 
> extents

Fixed.

--D

> > +.PP
> > +.I freeino
> > +is the number of inode records that are not in use within the space that has
> > +been allocated for them.
> > +.PP
> > +.I allocino
> > +is the number of inode records for which space has been allocated.
> > +.SH RETURN VALUE
> > +On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error.
> > +.PP
> > +.SH ERRORS
> > +Error codes can be one of, but are not limited to, the following:
> > +.TP
> > +.B EFSBADCRC
> > +Metadata checksum validation failed while performing the query.
> > +.TP
> > +.B EFSCORRUPTED
> > +Metadata corruption was encountered while performing the query.
> > +.TP
> > +.B EINVAL
> > +The specified allocation group number is not valid for this filesystem.
> > +.TP
> > +.B EIO
> > +An I/O error was encountered while performing the query.
> > +.SH CONFORMING TO
> > +This API is specific to XFS filesystem on the Linux kernel.
> > +.SH SEE ALSO
> > +.BR ioctl (2)
> > diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> > index 148119a9..007f7d58 100644
> > --- a/man/man3/xfsctl.3
> > +++ b/man/man3/xfsctl.3
> > @@ -390,6 +390,12 @@ See
> >  .BR ioctl_xfs_scrub_metadata (2)
> >  for more information.
> >  
> > +.TP
> > +.B XFS_IOC_FSCOUNTS
> > +See
> > +.BR ioctl_xfs_fscounts (2)
> > +for more information.
> > +
> >  .PP
> >  .nf
> >  .B XFS_IOC_THAW
> > @@ -398,16 +404,11 @@ for more information.
> >  .B XFS_IOC_SET_RESBLKS
> >  .B XFS_IOC_FSGROWFSDATA
> >  .B XFS_IOC_FSGROWFSLOG
> > -.B XFS_IOC_FSGROWFSRT
> >  .fi
> >  .TP
> > -.B XFS_IOC_FSCOUNTS
> > +.B XFS_IOC_FSGROWFSRT
> >  These interfaces are used to implement various filesystem internal
> >  operations on XFS filesystems.
> > -For
> > -.B XFS_FS_COUNTS
> > -(get filesystem dynamic global information), the output structure is of type
> > -.BR xfs_fsop_counts_t .
> >  The remainder of these operations will not be described further
> >  as they are not of general use to applications.
> >  
> > @@ -416,6 +417,7 @@ as they are not of general use to applications.
> >  .BR ioctl_xfs_fsop_geometry (2),
> >  .BR ioctl_xfs_fsbulkstat (2),
> >  .BR ioctl_xfs_fsinumbers (2),
> > +.BR ioctl_xfs_fscounts (2),
> >  .BR fstatfs (2),
> >  .BR statfs (2),
> >  .BR xfs (5),
> > 

Re: [PATCH 7/9] libxfs: break out the RESBLKS manpage

[Darrick J. Wong]

On Mon, Jun 17, 2019 at 12:15:40PM -0500, Eric Sandeen wrote:
> On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> > 
> > Create a separate manual page for the RESBLKS ioctls so we can document
> > how they work.
> > 
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> >  man/man2/ioctl_xfs_getresblks.2 |   65 +++++++++++++++++++++++++++++++++++++++
> >  man/man3/xfsctl.3               |   14 +++++++-
> >  2 files changed, 77 insertions(+), 2 deletions(-)
> >  create mode 100644 man/man2/ioctl_xfs_getresblks.2
> > 
> > 
> > diff --git a/man/man2/ioctl_xfs_getresblks.2 b/man/man2/ioctl_xfs_getresblks.2
> > new file mode 100644
> > index 00000000..57533927
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_getresblks.2
> > @@ -0,0 +1,65 @@
> > +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> > +.\"
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-GETRESBLKS 2 2019-04-16 "XFS"
> > +.SH NAME
> > +ioctl_xfs_getresblks \- query XFS summary counter information
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <xfs/xfs_fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_GET_RESBLKS, struct xfs_fsop_resblks *" arg );
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_SET_RESBLKS, struct xfs_fsop_resblks *" arg );
> > +.SH DESCRIPTION
> > +Query or set the free space reservation information.
> > +These blocks are reserved by the filesystem as a last-ditch attempt to prevent
> 
> last-ditch is a bit colloquial and possibly not fun for translators?
> 
> s/a last-ditch/an/

"...as a final attempt to prevent metadata update failures..." ?

--D

> > +metadata update failures due to insufficient space.
> > +Only the system administrator can call these ioctls, because overriding the
> > +defaults is extremely dangerous and should never be tried by anyone.
> > +.PP
> > +The reservation information is conveyed in a structure of the following form:
> > +.PP
> > +.in +4n
> > +.nf
> > +struct xfs_fsop_resblks {
> > +	__u64  resblks;
> > +	__u64  resblks_avail;
> > +};
> > +.fi
> > +.in
> > +.PP
> > +.I resblks
> > +is the number of blocks that the filesystem will try to maintain to prevent
> > +critical out of space situations.
> > +.PP
> > +.I resblks_avail
> > +is the number of reserved blocks remaining.
> > +.SH RETURN VALUE
> > +On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error.
> > +.PP
> > +.SH ERRORS
> > +Error codes can be one of, but are not limited to, the following:
> > +.TP
> > +.B EFSBADCRC
> > +Metadata checksum validation failed while performing the query.
> > +.TP
> > +.B EFSCORRUPTED
> > +Metadata corruption was encountered while performing the query.
> > +.TP
> > +.B EINVAL
> > +The specified allocation group number is not valid for this filesystem.
> > +.TP
> > +.B EIO
> > +An I/O error was encountered while performing the query.
> > +.TP
> > +.B EPERM
> > +Caller does not have permission to call this ioctl.
> > +.SH CONFORMING TO
> > +This API is specific to XFS filesystem on the Linux kernel.
> > +.SH SEE ALSO
> > +.BR ioctl (2)
> > diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> > index 007f7d58..25e51417 100644
> > --- a/man/man3/xfsctl.3
> > +++ b/man/man3/xfsctl.3
> > @@ -396,12 +396,21 @@ See
> >  .BR ioctl_xfs_fscounts (2)
> >  for more information.
> >  
> > +.TP
> > +.nf
> > +.B XFS_IOC_GET_RESBLKS
> > +.fi
> > +.TP
> > +.B XFS_IOC_SET_RESBLKS
> > +See
> > +.BR ioctl_xfs_getresblks (2)
> > +for more information.
> > +Save yourself a lot of frustration and avoid these ioctls.
> > +
> >  .PP
> >  .nf
> >  .B XFS_IOC_THAW
> >  .B XFS_IOC_FREEZE
> > -.B XFS_IOC_GET_RESBLKS
> > -.B XFS_IOC_SET_RESBLKS
> >  .B XFS_IOC_FSGROWFSDATA
> >  .B XFS_IOC_FSGROWFSLOG
> >  .fi
> > @@ -418,6 +427,7 @@ as they are not of general use to applications.
> >  .BR ioctl_xfs_fsbulkstat (2),
> >  .BR ioctl_xfs_fsinumbers (2),
> >  .BR ioctl_xfs_fscounts (2),
> > +.BR ioctl_xfs_getresblks (2),
> >  .BR fstatfs (2),
> >  .BR statfs (2),
> >  .BR xfs (5),
> > 

Re: [PATCH 8/9] libxfs: break out GETBMAP manpage

[Darrick J. Wong]

On Mon, Jun 17, 2019 at 12:25:05PM -0500, Eric Sandeen wrote:
> On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> > 
> > Create a separate manual page for the BMAP ioctls so we can document how
> > they work.
> > 
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> >  man/man2/ioctl_xfs_getbmap.2 |  165 ++++++++++++++++++++++++++++++++++++++++++
> >  man/man3/xfsctl.3            |   61 +++-------------
> >  2 files changed, 175 insertions(+), 51 deletions(-)
> >  create mode 100644 man/man2/ioctl_xfs_getbmap.2
> > 
> > 
> > diff --git a/man/man2/ioctl_xfs_getbmap.2 b/man/man2/ioctl_xfs_getbmap.2
> > new file mode 100644
> > index 00000000..5097173b
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_getbmap.2
> > @@ -0,0 +1,165 @@
> > +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> > +.\"
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-GETBMAP 2 2019-04-11 "XFS"
> > +.SH NAME
> > +ioctl_xfs_getbmap \- query extent information for an open file
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <xfs/xfs_fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_GETBMAP, struct getbmap *" arg );
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_GETBMAPA, struct getbmap *" arg );
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_GETBMAPX, struct getbmapx *" arg );
> > +.SH DESCRIPTION
> > +Get the block map for a segment of a file in an XFS file system.
> > +The mapping information is conveyed in a structure of the following form:
> > +.PP
> > +.in +4n
> > +.nf
> > +struct getbmap {
> > +	__s64   bmv_offset;
> > +	__s64   bmv_block;
> > +	__s64   bmv_length;
> > +	__s32   bmv_count;
> > +	__s32   bmv_entries;
> > +};
> > +.fi
> > +.in
> > +.PP
> > +The
> > +.B XFS_IOC_GETBMAPX
> > +ioctl uses a larger version of that structure:
> > +.PP
> > +.in +4n
> > +.nf
> > +struct getbmapx {
> > +	__s64   bmv_offset;
> > +	__s64   bmv_block;
> > +	__s64   bmv_length;
> > +	__s32   bmv_count;
> > +	__s32   bmv_entries;
> > +	__s32   bmv_iflags;
> > +	__s32   bmv_oflags;
> > +	__s32   bmv_unused1;
> > +	__s32   bmv_unused2;
> > +};
> > +.fi
> > +.in
> > +.PP
> > +All sizes and offsets in the structure are in units of 512 bytes.
> > +.PP
> > +The first structure in the array is a header and the remaining structures in
> > +the array contain block map information on return.
> > +The header controls iterative calls to the command and should be filled out as
> > +follows:
> > +.TP
> > +.B bmv_offset
> > +The file offset of the area of interest in the file.
> > +.TP
> > +.B bmv_length
> > +The length of the area of interest in the file.
> > +If this value is set to -1, the length of the interesting area is the rest of
> > +the file.
> > +.TP
> > +.B bmv_count
> > +The length of the array, including this header.
> > +.TP
> > +.B bmv_entries
> > +The number of entries actually filled in by the call.
> > +This does not need to be filled out before the call.
> > +.TP
> > +.B bmv_iflags
> > +For the
> > +.B XFS_IOC_GETBMAPX
> > +function, this is a combination of the following flags:
> 
> specifically mention that they are ORed or is that obvious?

"...this is a bitmask containing a combination of the following
flags..."

> > +.RS 0.4i
> > +.TP
> > +.B BMV_IF_ATTRFORK
> > +Return information about the extended attribute fork.
> > +.TP
> > +.B BMV_IF_PREALLOC
> > +Return information about unwritten pre-allocated segments.
> > +.TP
> > +.B BMV_IF_DELALLOC
> > +Return information about delayed allocation reservation segments.
> > +.TP
> > +.B BMV_IF_NO_HOLES
> > +Do not return information about holes.
> > +.RE
> > +.PD 1
> 
> perhaps mention that others (bmv_block ...) are ignored in the header?

Ok.

> > +
> > +.PP
> > +On return from a call, the header is updated so that the command can be
> > +reused to obtain more information without re-initializing the structures.
> > +The remainder of the array will be filled out by the call as follows:
> > +
> > +.TP
> > +.B bmv_offset
> > +File offset of segment.
> > +.TP
> > +.B bmv_block
> > +Physical starting block of segment.
> > +If this is -1, then the segment is a hole.
> > +.TP
> > +.B bmv_length
> > +Length of segment.
> > +.TP
> > +.B bmv_oflags
> > +The
> > +.B XFS_IOC_GETBMAPX
> > +function will fill this field with a combination of the following flags:
> > +.RS 0.4i
> > +.TP
> > +.B BMV_OF_PREALLOC
> > +The segment is an unwritten pre-allocation.
> > +.TP
> > +.B BMV_OF_DELALLOC
> > +The segment is a delayed allocation reservation.
> > +.TP
> > +.B BMV_OF_LAST
> > +This segment is the last in the file.
> > +.TP
> > +.B BMV_OF_SHARED
> > +This segment shares blocks with other files.
> > +.RE
> > +.PD 1
> > +.PP
> 
> .. and maybe mention that i.e. bmv_count is unused in the
> array of records? *shrug*

Ok.

--D

> > +The
> > +.B XFS_IOC_GETBMAPA
> > +command is identical to
> > +.B XFS_IOC_GETBMAP
> > +except that information about the attribute fork of the file is returned.
> > +.SH RETURN VALUE
> > +On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error.
> > +.PP
> > +.SH ERRORS
> > +Error codes can be one of, but are not limited to, the following:
> > +.TP
> > +.B EFAULT
> > +The kernel was not able to copy into the userspace buffer.
> > +.TP
> > +.B EFSBADCRC
> > +Metadata checksum validation failed while performing the query.
> > +.TP
> > +.B EFSCORRUPTED
> > +Metadata corruption was encountered while performing the query.
> > +.TP
> > +.B EINVAL
> > +One of the arguments was not valid.
> > +.TP
> > +.B EIO
> > +An I/O error was encountered while performing the query.
> > +.TP
> > +.B ENOMEM
> > +There was insufficient memory to perform the query.
> > +.SH CONFORMING TO
> > +This API is specific to XFS filesystem on the Linux kernel.
> > +.SH SEE ALSO
> > +.BR ioctl (2)
> > diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> > index 25e51417..e0986afb 100644
> > --- a/man/man3/xfsctl.3
> > +++ b/man/man3/xfsctl.3
> > @@ -144,59 +144,17 @@ See
> >  .BR ioctl_xfs_fsgetxattr (2)
> >  for more information.
> >  
> > -.TP
> > -.B XFS_IOC_GETBMAP
> > -Get the block map for a segment of a file in an XFS file system.
> > -The final argument points to an arry of variables of type
> > -.BR "struct getbmap" .
> > -All sizes and offsets in the structure are in units of 512 bytes.
> > -The structure fields include:
> > -.B bmv_offset
> > -(file offset of segment),
> > -.B bmv_block
> > -(starting block of segment),
> > -.B bmv_length
> > -(length of segment),
> > -.B bmv_count
> > -(number of array entries, including the first), and
> > -.B bmv_entries
> > -(number of entries filled in).
> > -The first structure in the array is a header, and the remaining
> > -structures in the array contain block map information on return.
> > -The header controls iterative calls to the
> > +.PP
> > +.nf
> >  .B XFS_IOC_GETBMAP
> > -command.
> > -The caller fills in the
> > -.B bmv_offset
> > -and
> > -.B bmv_length
> > -fields of the header to indicate the area of interest in the file,
> > -and fills in the
> > -.B bmv_count
> > -field to indicate the length of the array.
> > -If the
> > -.B bmv_length
> > -value is set to \-1 then the length of the interesting area is the rest
> > -of the file.
> > -On return from a call, the header is updated so that the command can be
> > -reused to obtain more information, without re-initializing the structures.
> > -Also on return, the
> > -.B bmv_entries
> > -field of the header is set to the number of array entries actually filled in.
> > -The non-header structures will be filled in with
> > -.BR bmv_offset ,
> > -.BR bmv_block ,
> > -and
> > -.BR bmv_length .
> > -If a region of the file has no blocks (is a hole in the file) then the
> > -.B bmv_block
> > -field is set to \-1.
> > -
> > -.TP
> >  .B XFS_IOC_GETBMAPA
> > -Identical to
> > -.B XFS_IOC_GETBMAP
> > -except that information about the attribute fork of the file is returned.
> > +.fi
> > +.PD 0
> > +.TP
> > +.B XFS_IOC_GETBMAPX
> > +See
> > +.BR ioctl_getbmap (2)
> > +for more information.
> >  
> >  .PP
> >  .B XFS_IOC_RESVSP
> > @@ -428,6 +386,7 @@ as they are not of general use to applications.
> >  .BR ioctl_xfs_fsinumbers (2),
> >  .BR ioctl_xfs_fscounts (2),
> >  .BR ioctl_xfs_getresblks (2),
> > +.BR ioctl_xfs_getbmap (2),
> >  .BR fstatfs (2),
> >  .BR statfs (2),
> >  .BR xfs (5),
> > 

Re: [PATCH 9/9] libxfs: break out fs shutdown manpage

[Darrick J. Wong]

On Mon, Jun 17, 2019 at 12:27:26PM -0500, Eric Sandeen wrote:
> On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> > 
> > Create a separate manual page for the fs shutdown ioctl so we can
> > document how it works.
> > 
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> >  man/man2/ioctl_xfs_goingdown.2 |   61 ++++++++++++++++++++++++++++++++++++++++
> >  man/man3/xfsctl.3              |    7 +++++
> >  2 files changed, 68 insertions(+)
> >  create mode 100644 man/man2/ioctl_xfs_goingdown.2
> > 
> > 
> > diff --git a/man/man2/ioctl_xfs_goingdown.2 b/man/man2/ioctl_xfs_goingdown.2
> > new file mode 100644
> > index 00000000..e9a56f28
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_goingdown.2
> > @@ -0,0 +1,61 @@
> > +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> > +.\"
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-GOINGDOWN 2 2019-04-16 "XFS"
> > +.SH NAME
> > +ioctl_xfs_goingdown \- shut down an XFS filesystem
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <xfs/xfs_fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_GOINGDOWN, uint32_t " flags );
> > +.SH DESCRIPTION
> > +Shuts down a live XFS filesystem.
> > +This is a software initiated hard shutdown and should be avoided whenever
> > +possible.
> > +After this call completes, the filesystem will be totally unusable and must be
> > +unmounted.
> > +
> > +.PP
> > +.I flags
> > +can be one of the following:
> > +.RS 0.4i
> > +.TP
> > +.B XFS_FSOP_GOING_FLAGS_DEFAULT
> > +Flush all dirty data and in-core state to disk, flush the log, then shut down.
> > +.TP
> > +.B XFS_FSOP_GOING_FLAGS_LOGFLUSH
> > +Flush all pending transactions to the log, then shut down, leaving all dirty
> > +data unwritten.
> > +.TP
> > +.B XFS_FSOP_GOING_FLAGS_NOLOGFLUSH
> > +Shut down, leaving all dirty transactions and dirty data.
> 
> leaving it ... what?
> 
> Maybe "Shut down, without flushing any dirty transactions or data to disk."

"Shut down immediately, without writing pending transactions or dirty data
to disk." ?

--D

> 
> > +
> > +.SH RETURN VALUE
> > +On error, \-1 is returned, and
> > +.I errno
> > +is set to indicate the error.
> > +.PP
> > +.SH ERRORS
> > +Error codes can be one of, but are not limited to, the following:
> > +.TP
> > +.B EFSBADCRC
> > +Metadata checksum validation failed while performing the query.
> > +.TP
> > +.B EFSCORRUPTED
> > +Metadata corruption was encountered while performing the query.
> > +.TP
> > +.B EINVAL
> > +The specified allocation group number is not valid for this filesystem.
> > +.TP
> > +.B EIO
> > +An I/O error was encountered while performing the query.
> > +.TP
> > +.B EPERM
> > +Caller did not have permission to shut down the filesystem.
> > +.SH CONFORMING TO
> > +This API is specific to XFS filesystem on the Linux kernel.
> > +.SH SEE ALSO
> > +.BR ioctl (2)
> > diff --git a/man/man3/xfsctl.3 b/man/man3/xfsctl.3
> > index e0986afb..ca96a007 100644
> > --- a/man/man3/xfsctl.3
> > +++ b/man/man3/xfsctl.3
> > @@ -365,6 +365,12 @@ See
> >  for more information.
> >  Save yourself a lot of frustration and avoid these ioctls.
> >  
> > +.TP
> > +.B XFS_IOC_GOINGDOWN
> > +See
> > +.BR ioctl_xfs_goingdown (2)
> > +for more information.
> > +
> >  .PP
> >  .nf
> >  .B XFS_IOC_THAW
> > @@ -387,6 +393,7 @@ as they are not of general use to applications.
> >  .BR ioctl_xfs_fscounts (2),
> >  .BR ioctl_xfs_getresblks (2),
> >  .BR ioctl_xfs_getbmap (2),
> > +.BR ioctl_xfs_goingdown (2),
> >  .BR fstatfs (2),
> >  .BR statfs (2),
> >  .BR xfs (5),
> > 

Re: [PATCH 9/9] libxfs: break out fs shutdown manpage

[Eric Sandeen]

On 6/18/19 2:56 PM, Darrick J. Wong wrote:
> On Mon, Jun 17, 2019 at 12:27:26PM -0500, Eric Sandeen wrote:
>> On 6/7/19 2:29 PM, Darrick J. Wong wrote:
>>> From: Darrick J. Wong <darrick.wong@oracle.com>
>>>
>>> Create a separate manual page for the fs shutdown ioctl so we can
>>> document how it works.
>>>
>>> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
>>> ---
>>>  man/man2/ioctl_xfs_goingdown.2 |   61 ++++++++++++++++++++++++++++++++++++++++
>>>  man/man3/xfsctl.3              |    7 +++++
>>>  2 files changed, 68 insertions(+)
>>>  create mode 100644 man/man2/ioctl_xfs_goingdown.2
>>>
>>>
>>> diff --git a/man/man2/ioctl_xfs_goingdown.2 b/man/man2/ioctl_xfs_goingdown.2
>>> new file mode 100644
>>> index 00000000..e9a56f28
>>> --- /dev/null
>>> +++ b/man/man2/ioctl_xfs_goingdown.2
>>> @@ -0,0 +1,61 @@
>>> +.\" Copyright (c) 2019, Oracle.  All rights reserved.
>>> +.\"
>>> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
>>> +.\" SPDX-License-Identifier: GPL-2.0+
>>> +.\" %%%LICENSE_END
>>> +.TH IOCTL-XFS-GOINGDOWN 2 2019-04-16 "XFS"
>>> +.SH NAME
>>> +ioctl_xfs_goingdown \- shut down an XFS filesystem
>>> +.SH SYNOPSIS
>>> +.br
>>> +.B #include <xfs/xfs_fs.h>
>>> +.PP
>>> +.BI "int ioctl(int " fd ", XFS_IOC_GOINGDOWN, uint32_t " flags );
>>> +.SH DESCRIPTION
>>> +Shuts down a live XFS filesystem.
>>> +This is a software initiated hard shutdown and should be avoided whenever
>>> +possible.
>>> +After this call completes, the filesystem will be totally unusable and must be
>>> +unmounted.
>>> +
>>> +.PP
>>> +.I flags
>>> +can be one of the following:
>>> +.RS 0.4i
>>> +.TP
>>> +.B XFS_FSOP_GOING_FLAGS_DEFAULT
>>> +Flush all dirty data and in-core state to disk, flush the log, then shut down.
>>> +.TP
>>> +.B XFS_FSOP_GOING_FLAGS_LOGFLUSH
>>> +Flush all pending transactions to the log, then shut down, leaving all dirty
>>> +data unwritten.
>>> +.TP
>>> +.B XFS_FSOP_GOING_FLAGS_NOLOGFLUSH
>>> +Shut down, leaving all dirty transactions and dirty data.
>>
>> leaving it ... what?
>>
>> Maybe "Shut down, without flushing any dirty transactions or data to disk."
> 
> "Shut down immediately, without writing pending transactions or dirty data
> to disk." ?

The two other cases use "flush" terminology so I was sticking with that.  If
"write" is less jargon-y then I'd do it for all of them - using similar terminology
for all 3 cases helps the reader understand the differences more clearly, I think.

-Eric

Re: [PATCH 9/9] libxfs: break out fs shutdown manpage

[Darrick J. Wong]

On Tue, Jun 18, 2019 at 03:00:43PM -0500, Eric Sandeen wrote:
> 
> 
> On 6/18/19 2:56 PM, Darrick J. Wong wrote:
> > On Mon, Jun 17, 2019 at 12:27:26PM -0500, Eric Sandeen wrote:
> >> On 6/7/19 2:29 PM, Darrick J. Wong wrote:
> >>> From: Darrick J. Wong <darrick.wong@oracle.com>
> >>>
> >>> Create a separate manual page for the fs shutdown ioctl so we can
> >>> document how it works.
> >>>
> >>> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> >>> ---
> >>>  man/man2/ioctl_xfs_goingdown.2 |   61 ++++++++++++++++++++++++++++++++++++++++
> >>>  man/man3/xfsctl.3              |    7 +++++
> >>>  2 files changed, 68 insertions(+)
> >>>  create mode 100644 man/man2/ioctl_xfs_goingdown.2
> >>>
> >>>
> >>> diff --git a/man/man2/ioctl_xfs_goingdown.2 b/man/man2/ioctl_xfs_goingdown.2
> >>> new file mode 100644
> >>> index 00000000..e9a56f28
> >>> --- /dev/null
> >>> +++ b/man/man2/ioctl_xfs_goingdown.2
> >>> @@ -0,0 +1,61 @@
> >>> +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> >>> +.\"
> >>> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> >>> +.\" SPDX-License-Identifier: GPL-2.0+
> >>> +.\" %%%LICENSE_END
> >>> +.TH IOCTL-XFS-GOINGDOWN 2 2019-04-16 "XFS"
> >>> +.SH NAME
> >>> +ioctl_xfs_goingdown \- shut down an XFS filesystem
> >>> +.SH SYNOPSIS
> >>> +.br
> >>> +.B #include <xfs/xfs_fs.h>
> >>> +.PP
> >>> +.BI "int ioctl(int " fd ", XFS_IOC_GOINGDOWN, uint32_t " flags );
> >>> +.SH DESCRIPTION
> >>> +Shuts down a live XFS filesystem.
> >>> +This is a software initiated hard shutdown and should be avoided whenever
> >>> +possible.
> >>> +After this call completes, the filesystem will be totally unusable and must be
> >>> +unmounted.
> >>> +
> >>> +.PP
> >>> +.I flags
> >>> +can be one of the following:
> >>> +.RS 0.4i
> >>> +.TP
> >>> +.B XFS_FSOP_GOING_FLAGS_DEFAULT
> >>> +Flush all dirty data and in-core state to disk, flush the log, then shut down.
> >>> +.TP
> >>> +.B XFS_FSOP_GOING_FLAGS_LOGFLUSH
> >>> +Flush all pending transactions to the log, then shut down, leaving all dirty
> >>> +data unwritten.
> >>> +.TP
> >>> +.B XFS_FSOP_GOING_FLAGS_NOLOGFLUSH
> >>> +Shut down, leaving all dirty transactions and dirty data.
> >>
> >> leaving it ... what?
> >>
> >> Maybe "Shut down, without flushing any dirty transactions or data to disk."
> > 
> > "Shut down immediately, without writing pending transactions or dirty data
> > to disk." ?
> 
> The two other cases use "flush" terminology so I was sticking with that.  If
> "write" is less jargon-y then I'd do it for all of them - using similar terminology
> for all 3 cases helps the reader understand the differences more clearly, I think.

I ended up editing it some more:

       flags can be one of the following:

           XFS_FSOP_GOING_FLAGS_DEFAULT
                  Flush all dirty data  and  in-core  state  to  disk,
                  flush  pending  transactions  to  the  log, and shut
                  down.

           XFS_FSOP_GOING_FLAGS_LOGFLUSH
                  Flush all pending transactions to the log  and  shut
                  down, leaving all dirty data unwritten.

           XFS_FSOP_GOING_FLAGS_NOLOGFLUSH
                  Shut   down  immediately,  without  writing  pending
                  transactions or dirty data to disk.

--D

> -Eric