On 9/25/19 4:32 PM, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@xxxxxxxxxx>
>
> Add a manpage describing the new v5 XFS_IOC_INUMBERS ioctl.
>
> Signed-off-by: Darrick J. Wong <darrick.wong@xxxxxxxxxx>
> ---
> 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).
>
