[2/4] man: add documentation for v5 inumbers ioctl
diff mbox series

Message ID 156944715928.297379.7728068992247988597.stgit@magnolia
State New
Headers show
Series
  • xfsprogs: port utilities to bulkstat v5
Related show

Commit Message

Darrick J. Wong Sept. 25, 2019, 9:32 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

Comments

Eric Sandeen Sept. 26, 2019, 6:36 p.m. UTC | #1
On 9/25/19 4:32 PM, Darrick J. Wong wrote:
> 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 --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.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-INUMBERS 2 2019-05-23 "XFS"
> +.SH NAME
> +ioctl_xfs_inumbers \- query allocation information for groups of XFS inodes
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_INUMBERS, struct xfs_inumbers_req *" arg );
> +.SH DESCRIPTION
> +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:
> +.PP
> +.in +4n
> +.nf
> +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];
> +};
> +.fi
> +.in
> +.PP
> +.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.

it needs to be, though, because icount has a different meaning here; it's
not number of inodes, it's number-of-batches-of-64-inodes, right?

and the bulkstat manpage says "hdr.icount is the number of inodes to examine."

Ok, you suggested on IRC< changing the bulkstat manpage to say "records" not
"inodes" which would work too.

> +
> +.PP
> +.I inumbers
> +is an array of
> +.B struct xfs_inumbers
> +which is described below.
> +The array must have at least
> +.I icount
> +elements.
> +.PP
> +.in +4n
> +.nf
> +struct xfs_inumbers {
> +	uint64_t                xi_startino;
> +	uint64_t                xi_allocmask;
> +	uint8_t                 xi_alloccount;
> +	uint8_t                 xi_version;
> +	uint8_t                 xi_padding[6];
> +};
> +.fi
> +.in
> +.PP
> +This structure describes inode usage information for a group of 64 consecutive
> +inode numbers.
> +.PP
> +.I xi_startino
> +is the first inode number of this group.
> +.PP
> +.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.
> +.PP
> +.I xi_alloccount
> +is the number of inodes in this group that are allocated.
> +This should be equal to popcnt(xi_allocmask).
> +.PP
> +.I xi_version
> +is the version of this data structure.
> +Currently, only 1 or 5 are supported.

I find myself wondering what the differences between these versions
are...?

> +.PP
> +.I xi_padding[6]
> +is 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 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),
> +.BR ioctl_xfs_bulkstat (2).
>
Eric Sandeen Sept. 26, 2019, 6:49 p.m. UTC | #2
On 9/26/19 1:36 PM, Eric Sandeen wrote:
>> +.I xi_version
>> +is the version of this data structure.
>> +Currently, only 1 or 5 are supported.
> I find myself wondering what the differences between these versions
> are...?
> 

ok, the structure defined in this manpage is v5; the kernel will never return
xi_version = 1.  So I think maybe:

"... is the version of this data structure.  The structure defined here is
version 5."

-Eric

Patch
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.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-INUMBERS 2 2019-05-23 "XFS"
+.SH NAME
+ioctl_xfs_inumbers \- query allocation information for groups of XFS inodes
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_INUMBERS, struct xfs_inumbers_req *" arg );
+.SH DESCRIPTION
+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:
+.PP
+.in +4n
+.nf
+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];
+};
+.fi
+.in
+.PP
+.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.
+
+.PP
+.I inumbers
+is an array of
+.B struct xfs_inumbers
+which is described below.
+The array must have at least
+.I icount
+elements.
+.PP
+.in +4n
+.nf
+struct xfs_inumbers {
+	uint64_t                xi_startino;
+	uint64_t                xi_allocmask;
+	uint8_t                 xi_alloccount;
+	uint8_t                 xi_version;
+	uint8_t                 xi_padding[6];
+};
+.fi
+.in
+.PP
+This structure describes inode usage information for a group of 64 consecutive
+inode numbers.
+.PP
+.I xi_startino
+is the first inode number of this group.
+.PP
+.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.
+.PP
+.I xi_alloccount
+is the number of inodes in this group that are allocated.
+This should be equal to popcnt(xi_allocmask).
+.PP
+.I xi_version
+is the version of this data structure.
+Currently, only 1 or 5 are supported.
+.PP
+.I xi_padding[6]
+is 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 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),
+.BR ioctl_xfs_bulkstat (2).