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

Dave Chinner
2019-08-30T05:53:53Z

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.
--
Dave Chinner
david@fromorbit.com