| Message ID | 156944715928.297379.7728068992247988597.stgit@magnolia (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | xfsprogs: port utilities to bulkstat v5 | expand |
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). >
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
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).