diff mbox series

[2/5] man: add documentation for v5 inumbers ioctl

Message ID 156685454401.2840332.2689052873122428637.stgit@magnolia
State Superseded
Headers show
Series xfsprogs: port utilities to bulkstat v5 | expand

Commit Message

Darrick J. Wong Aug. 26, 2019, 9:22 p.m. UTC
From: Darrick J. Wong <darrick.wong@oracle.com>

Add a manpage describing the new v5 XFS_IOC_INUMBERS ioctl.

Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
 man/man2/ioctl_xfs_inumbers.2 |  118 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 118 insertions(+)
 create mode 100644 man/man2/ioctl_xfs_inumbers.2
diff mbox series


diff --git a/man/man2/ioctl_xfs_inumbers.2 b/man/man2/ioctl_xfs_inumbers.2
new file mode 100644
index 00000000..b1e854d3
--- /dev/null
+++ b/man/man2/ioctl_xfs_inumbers.2
@@ -0,0 +1,118 @@ 
+.\" Copyright (c) 2019, Oracle.  All rights reserved.
+.\" SPDX-License-Identifier: GPL-2.0+
+.TH IOCTL-XFS-INUMBERS 2 2019-05-23 "XFS"
+ioctl_xfs_inumbers \- query allocation information for groups of XFS inodes
+.B #include <xfs/xfs_fs.h>
+.BI "int ioctl(int " fd ", XFS_IOC_INUMBERS, struct xfs_inumbers_req *" arg );
+Query inode allocation information for groups of XFS inodes.
+This ioctl uses
+.B struct xfs_inumbers_req
+to set up a bulk transfer with the kernel:
+.in +4n
+struct xfs_inumbers_req {
+	struct xfs_bulk_ireq    hdr;
+	struct xfs_inumbers     inumbers[];
+struct xfs_bulk_ireq {
+	uint64_t                ino;
+	uint32_t                flags;
+	uint32_t                icount;
+	uint32_t                ocount;
+	uint32_t                agno;
+	uint64_t                reserved[5];
+.I hdr
+describes the information to query.
+The layout and behavior are documented in the
+.BR ioctl_xfs_bulkstat (2)
+manpage and will not be discussed further here.
+.I inumbers
+is an array of
+.B struct xfs_inumbers
+which is described below.
+The array must have at least
+.I icount
+.in +4n
+struct xfs_inumbers {
+	uint64_t                xi_startino;
+	uint64_t                xi_allocmask;
+	uint8_t                 xi_alloccount;
+	uint8_t                 xi_version;
+	uint8_t                 xi_padding[6];
+This structure describes inode usage information for a group of 64 consecutive
+inode numbers.
+.I xi_startino
+is the first inode number of this group.
+.I xi_allocmask
+is a bitmask telling which inodes in this group are allocated.
+To clarify, bit
+.B N
+is set if inode
+.BR xi_startino + N
+is allocated.
+.I xi_alloccount
+is the number of inodes in this group that are allocated.
+This should be equal to popcnt(xi_allocmask).
+.I xi_version
+is the version of this data structure.
+Currently, only 1 or 5 are supported.
+.I xi_padding[6]
+is zeroed.
+On error, \-1 is returned, and
+.I errno
+is set to indicate the error.
+Error codes can be one of, but are not limited to, the following:
+The kernel was not able to copy into the userspace buffer.
+Metadata checksum validation failed while performing the query.
+Metadata corruption was encountered while performing the query.
+One of the arguments was not valid.
+An I/O error was encountered while performing the query.
+There was insufficient memory to perform the query.
+This API is specific to XFS filesystem on the Linux kernel.
+.BR ioctl (2),
+.BR ioctl_xfs_bulkstat (2).