diff mbox series

[06/12] man: document the new allocation group geometry ioctl

Message ID 156633310832.1215978.10494838202211430225.stgit@magnolia (mailing list archive)
State Superseded
Headers show
Series xfsprogs-5.3: various fixes | expand

Commit Message

Darrick J. Wong Aug. 20, 2019, 8:31 p.m. UTC 
From: Darrick J. Wong <darrick.wong@oracle.com>

Document the new ioctl to describe an allocation group's geometry.

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

Comments

Dave Chinner Aug. 30, 2019, 5:53 a.m. UTC | #1 
On Tue, Aug 20, 2019 at 01:31:48PM -0700, Darrick J. Wong wrote:
> From: Darrick J. Wong <darrick.wong@oracle.com>
> 
> Document the new ioctl to describe an allocation group's geometry.
> 
> Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> ---
>  man/man2/ioctl_xfs_ag_geometry.2 |   74 ++++++++++++++++++++++++++++++++++++++
>  man/man3/xfsctl.3                |    6 +++
>  2 files changed, 80 insertions(+)
>  create mode 100644 man/man2/ioctl_xfs_ag_geometry.2
> 
> 
> diff --git a/man/man2/ioctl_xfs_ag_geometry.2 b/man/man2/ioctl_xfs_ag_geometry.2
> new file mode 100644
> index 00000000..5dfe0d08
> --- /dev/null
> +++ b/man/man2/ioctl_xfs_ag_geometry.2
> @@ -0,0 +1,74 @@
> +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> +.\"
> +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> +.\" SPDX-License-Identifier: GPL-2.0+
> +.\" %%%LICENSE_END
> +.TH IOCTL-XFS-AG-GEOMETRY 2 2019-04-11 "XFS"
> +.SH NAME
> +ioctl_xfs_ag_geometry \- query XFS allocation group geometry information
> +.SH SYNOPSIS
> +.br
> +.B #include <xfs/xfs_fs.h>
> +.PP
> +.BI "int ioctl(int " fd ", XFS_IOC_AG_GEOMETRY, struct xfs_ag_geometry *" arg );
> +.SH DESCRIPTION
> +This XFS ioctl retrieves the geometry information for a given allocation group.
> +The geometry information is conveyed in a structure of the following form:
> +.PP
> +.in +4n
> +.nf
> +struct xfs_ag_geometry {
> +	uint32_t  ag_number;
> +	uint32_t  ag_length;
> +	uint32_t  ag_freeblks;
> +	uint32_t  ag_icount;
> +	uint32_t  ag_ifree;
> +	uint32_t  ag_sick;
> +	uint32_t  ag_checked;
> +	uint32_t  ag_reserved32;
> +	uint64_t  ag_reserved[12];

Where's the flags field for feature versioning? Please don't tell me
we merged an ioctl structure without a flags or version field in
it...

> +};
> +.fi
> +.in
> +.TP
> +.I ag_number
> +The number of allocation group that the caller wishes to learn about.

"the index of"....

"The number of" is easily confused with a quantity....

Is this an input or an output?

> +.TP
> +.I ag_length
> +Length of the allocation group, in units of filesystem blocks.

The length of the AG is returned in this field, in units....

Same for the rest...

> +.TP
> +.I ag_freeblks
> +Number of free blocks in the allocation group, in units of filesystem blocks.
> +.TP
> +.I ag_icount
> +Number of inode records allocated in this allocation group.
> +.TP
> +.I ag_ifree
> +Number of unused inode records (of the space allocated) in this allocation
> +group.
> +.TP
> +.IR ag_reserved " and " ag_reserved32
> +Will be set to zero.

It would be better to say "all reserved feilds will be set to zero
on return" so that we don't have to change this every time we rev
the structure....

Cheers,

Dave.
Darrick J. Wong Aug. 30, 2019, 8:48 p.m. UTC | #2 
On Fri, Aug 30, 2019 at 03:53:47PM +1000, Dave Chinner wrote:
> On Tue, Aug 20, 2019 at 01:31:48PM -0700, Darrick J. Wong wrote:
> > From: Darrick J. Wong <darrick.wong@oracle.com>
> > 
> > Document the new ioctl to describe an allocation group's geometry.
> > 
> > Signed-off-by: Darrick J. Wong <darrick.wong@oracle.com>
> > ---
> >  man/man2/ioctl_xfs_ag_geometry.2 |   74 ++++++++++++++++++++++++++++++++++++++
> >  man/man3/xfsctl.3                |    6 +++
> >  2 files changed, 80 insertions(+)
> >  create mode 100644 man/man2/ioctl_xfs_ag_geometry.2
> > 
> > 
> > diff --git a/man/man2/ioctl_xfs_ag_geometry.2 b/man/man2/ioctl_xfs_ag_geometry.2
> > new file mode 100644
> > index 00000000..5dfe0d08
> > --- /dev/null
> > +++ b/man/man2/ioctl_xfs_ag_geometry.2
> > @@ -0,0 +1,74 @@
> > +.\" Copyright (c) 2019, Oracle.  All rights reserved.
> > +.\"
> > +.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
> > +.\" SPDX-License-Identifier: GPL-2.0+
> > +.\" %%%LICENSE_END
> > +.TH IOCTL-XFS-AG-GEOMETRY 2 2019-04-11 "XFS"
> > +.SH NAME
> > +ioctl_xfs_ag_geometry \- query XFS allocation group geometry information
> > +.SH SYNOPSIS
> > +.br
> > +.B #include <xfs/xfs_fs.h>
> > +.PP
> > +.BI "int ioctl(int " fd ", XFS_IOC_AG_GEOMETRY, struct xfs_ag_geometry *" arg );
> > +.SH DESCRIPTION
> > +This XFS ioctl retrieves the geometry information for a given allocation group.
> > +The geometry information is conveyed in a structure of the following form:
> > +.PP
> > +.in +4n
> > +.nf
> > +struct xfs_ag_geometry {
> > +	uint32_t  ag_number;
> > +	uint32_t  ag_length;
> > +	uint32_t  ag_freeblks;
> > +	uint32_t  ag_icount;
> > +	uint32_t  ag_ifree;
> > +	uint32_t  ag_sick;
> > +	uint32_t  ag_checked;
> > +	uint32_t  ag_reserved32;
> > +	uint64_t  ag_reserved[12];
> 
> Where's the flags field for feature versioning? Please don't tell me
> we merged an ioctl structure without a flags or version field in
> it...

Yes, we did, though the "reserved fields are always zeroed" enables us
to retroactively define this to v0 of the structure.

> > +};
> > +.fi
> > +.in
> > +.TP
> > +.I ag_number
> > +The number of allocation group that the caller wishes to learn about.
> 
> "the index of"....
> 
> "The number of" is easily confused with a quantity....
> 
> Is this an input or an output?

Purely an input.

"The caller must set this field to the index of the allocation group
that the caller wishes to learn about." ?

> > +.TP
> > +.I ag_length
> > +Length of the allocation group, in units of filesystem blocks.
> 
> The length of the AG is returned in this field, in units....
> 
> Same for the rest...

Ok.

> > +.TP
> > +.I ag_freeblks
> > +Number of free blocks in the allocation group, in units of filesystem blocks.
> > +.TP
> > +.I ag_icount
> > +Number of inode records allocated in this allocation group.
> > +.TP
> > +.I ag_ifree
> > +Number of unused inode records (of the space allocated) in this allocation
> > +group.
> > +.TP
> > +.IR ag_reserved " and " ag_reserved32
> > +Will be set to zero.
> 
> It would be better to say "all reserved feilds will be set to zero
> on return" so that we don't have to change this every time we rev
> the structure....

Ok.

--D

> Cheers,
> 
> Dave.
> -- 
> Dave Chinner
> david@fromorbit.com
Dave Chinner Sept. 2, 2019, 10:36 p.m. UTC | #3 
On Fri, Aug 30, 2019 at 01:48:49PM -0700, Darrick J. Wong wrote:
> On Fri, Aug 30, 2019 at 03:53:47PM +1000, Dave Chinner wrote:
> > On Tue, Aug 20, 2019 at 01:31:48PM -0700, Darrick J. Wong wrote:
> > > +	uint64_t  ag_reserved[12];
> > 
> > Where's the flags field for feature versioning? Please don't tell me
> > we merged an ioctl structure without a flags or version field in
> > it...
> 
> Yes, we did, though the "reserved fields are always zeroed" enables us
> to retroactively define this to v0 of the structure.

OK, but this is an input/output structure, not an output-only
structure, so the flags field needs to cover what features the
caller might be expecting the kernel to return, too.,,

> > > +};
> > > +.fi
> > > +.in
> > > +.TP
> > > +.I ag_number
> > > +The number of allocation group that the caller wishes to learn about.
> > 
> > "the index of"....
> > 
> > "The number of" is easily confused with a quantity....
> > 
> > Is this an input or an output?
> 
> Purely an input.
> 
> "The caller must set this field to the index of the allocation group
> that the caller wishes to learn about." ?

*nod*.

Cheers,

Dave.
Darrick J. Wong Sept. 3, 2019, 3:22 a.m. UTC | #4 
On Tue, Sep 04, 2019 at 08:36:57AM +1000, Dave Chinner wrote:
> On Fri, Aug 30, 2019 at 01:48:49PM -0700, Darrick J. Wong wrote:
> > On Fri, Aug 30, 2019 at 03:53:47PM +1000, Dave Chinner wrote:
> > > On Tue, Aug 20, 2019 at 01:31:48PM -0700, Darrick J. Wong wrote:
> > > > +	uint64_t  ag_reserved[12];
> > > 
> > > Where's the flags field for feature versioning? Please don't tell me
> > > we merged an ioctl structure without a flags or version field in
> > > it...
> > 
> > Yes, we did, though the "reserved fields are always zeroed" enables us
> > to retroactively define this to v0 of the structure.
> 
> OK, but this is an input/output structure, not an output-only
> structure, so the flags field needs to cover what features the
> caller might be expecting the kernel to return, too.,,

What do you think of the v2 "xfs: define a flags field for the AG
geometry ioctl structure" patch, then?

--D

> > > > +};
> > > > +.fi
> > > > +.in
> > > > +.TP
> > > > +.I ag_number
> > > > +The number of allocation group that the caller wishes to learn about.
> > > 
> > > "the index of"....
> > > 
> > > "The number of" is easily confused with a quantity....
> > > 
> > > Is this an input or an output?
> > 
> > Purely an input.
> > 
> > "The caller must set this field to the index of the allocation group
> > that the caller wishes to learn about." ?
> 
> *nod*.
> 
> Cheers,
> 
> Dave.
> -- 
> Dave Chinner
> david@fromorbit.com
diff mbox series

Patch

diff --git a/man/man2/ioctl_xfs_ag_geometry.2 b/man/man2/ioctl_xfs_ag_geometry.2
new file mode 100644
index 00000000..5dfe0d08
--- /dev/null
+++ b/man/man2/ioctl_xfs_ag_geometry.2
@@ -0,0 +1,74 @@ 
+.\" Copyright (c) 2019, Oracle.  All rights reserved.
+.\"
+.\" %%%LICENSE_START(GPLv2+_DOC_FULL)
+.\" SPDX-License-Identifier: GPL-2.0+
+.\" %%%LICENSE_END
+.TH IOCTL-XFS-AG-GEOMETRY 2 2019-04-11 "XFS"
+.SH NAME
+ioctl_xfs_ag_geometry \- query XFS allocation group geometry information
+.SH SYNOPSIS
+.br
+.B #include <xfs/xfs_fs.h>
+.PP
+.BI "int ioctl(int " fd ", XFS_IOC_AG_GEOMETRY, struct xfs_ag_geometry *" arg );
+.SH DESCRIPTION
+This XFS ioctl retrieves the geometry information for a given allocation group.
+The geometry information is conveyed in a structure of the following form:
+.PP
+.in +4n
+.nf
+struct xfs_ag_geometry {
+	uint32_t  ag_number;
+	uint32_t  ag_length;
+	uint32_t  ag_freeblks;
+	uint32_t  ag_icount;
+	uint32_t  ag_ifree;
+	uint32_t  ag_sick;
+	uint32_t  ag_checked;
+	uint32_t  ag_reserved32;
+	uint64_t  ag_reserved[12];
+};
+.fi
+.in
+.TP
+.I ag_number
+The number of allocation group that the caller wishes to learn about.
+.TP
+.I ag_length
+Length of the allocation group, in units of filesystem blocks.
+.TP
+.I ag_freeblks
+Number of free blocks in the allocation group, in units of filesystem blocks.
+.TP
+.I ag_icount
+Number of inode records allocated in this allocation group.
+.TP
+.I ag_ifree
+Number of unused inode records (of the space allocated) in this allocation
+group.
+.TP
+.IR ag_reserved " and " ag_reserved32
+Will be set to zero.
+.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 7e6588b8..dfebd12d 100644
--- a/man/man3/xfsctl.3
+++ b/man/man3/xfsctl.3
@@ -336,6 +336,12 @@  See
 .BR ioctl_xfs_fsop_geometry (2)
 for more information.
 
+.TP
+.B XFS_IOC_AG_GEOMETRY
+See
+.BR ioctl_xfs_ag_geometry (2)
+for more information.
+
 .TP
 .BR XFS_IOC_FSBULKSTAT " or " XFS_IOC_FSBULKSTAT_SINGLE
 See