From mboxrd@z Thu Jan  1 00:00:00 1970
Return-Path: <linux-xfs-owner@vger.kernel.org>
Received: from aserp2130.oracle.com ([141.146.126.79]:56124 "EHLO
        aserp2130.oracle.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org
        with ESMTP id S2403835AbfFLGwQ (ORCPT
        <rfc822;linux-xfs@vger.kernel.org>); Wed, 12 Jun 2019 02:52:16 -0400
Date: Tue, 11 Jun 2019 23:47:10 -0700
From: "Darrick J. Wong" <darrick.wong@oracle.com>
Subject: Re: [PATCH xfsprogs manual] Inconsistency between the code and the
 manual page
Message-ID: <20190612064710.GY1871505@magnolia>
References: <a8dbaa7f-f89c-8a78-1fc6-3626f6b3f873@linux.alibaba.com>
MIME-Version: 1.0
Content-Type: text/plain; charset=iso-8859-1
Content-Disposition: inline
Content-Transfer-Encoding: 8bit
In-Reply-To: <a8dbaa7f-f89c-8a78-1fc6-3626f6b3f873@linux.alibaba.com>
Sender: linux-xfs-owner@vger.kernel.org
List-ID: <linux-xfs.vger.kernel.org>
List-Id: xfs
To: Alvin Zheng <Alvin@linux.alibaba.com>
Cc: linux-xfs <linux-xfs@vger.kernel.org>, caspar <caspar@linux.alibaba.com>

On Wed, Jun 12, 2019 at 01:20:46PM +0800, Alvin Zheng wrote:
> Hi,
> 
>     The manual page of mkfs.xfs (xfsprogs-5.0.0) says "When specifying 
> parameters in units of sectors or filesystem blocks, the -s option or the -b
> option first needs to be added to the command line.  Failure to specify the
> size of the units will result in illegal value errors when parameters are
> quantified in those units". However, I read the code and found that if the
> size of the block and sector is not specified, the default size (block: 4k,
> sector: 512B) will be used. Therefore, the following commands can work
> normally in xfsprogs-5.0.0.
> 
>      mkfs.xfs -n size=2b /dev/vdc
>      mkfs.xfs -d agsize=8192b /dev/vdc
> 
>     So I think the manual of mkfs.xfs should be updated as follows. Any
> ideas?

/me vaguely remembers some sort of discussion years ago around unease
that one can specify a block count without specifying the size of those
blocks...

...but to be honest, I don't really see why that would be a problem.
This seems fine to me, though I defer to Eric the Real Maintainer. :)

--D

> diff --git a/man/man8/mkfs.xfs.8 b/man/man8/mkfs.xfs.8
> index 4b8c78c..45d7a84 100644
> --- a/man/man8/mkfs.xfs.8
> +++ b/man/man8/mkfs.xfs.8
> @@ -115,9 +115,7 @@ When specifying parameters in units of sectors or
> filesystem blocks, the
>  .B \-s
>  option or the
>  .B \-b
> -option first needs to be added to the command line.
> -Failure to specify the size of the units will result in illegal value
> errors
> -when parameters are quantified in those units.
> +option can be used to specify the size of the sector or block. If the size
> of the block or sector is not specified, the default size (block: 4KiB,
> sector: 512B) will be used.
>  .PP
>  Many feature options allow an optional argument of 0 or 1, to explicitly
>  disable or enable the functionality.
> @@ -136,10 +134,6 @@ The filesystem block size is specified with a
>  in bytes. The default value is 4096 bytes (4 KiB), the minimum is 512, and
> the
>  maximum is 65536 (64 KiB).
>  .IP
> -To specify any options on the command line in units of filesystem blocks,
> this
> -option must be specified first so that the filesystem block size is
> -applied consistently to all options.
> -.IP
>  Although
>  .B mkfs.xfs
>  will accept any of these values and create a valid filesystem,
> @@ -894,10 +888,6 @@ is 512 bytes. The minimum value for sector size is
>  .I sector_size
>  must be a power of 2 size and cannot be made larger than the
>  filesystem block size.
> -.IP
> -To specify any options on the command line in units of sectors, this
> -option must be specified first so that the sector size is
> -applied consistently to all options.
>  .RE
>  .TP
>  .BI \-L " label"
> 
> 
>     Best regards,
> 
>     Alvin
>