bug#32242: dd help text lacks information about binary prefixes

[Wodry]

Am 21.07.2018 um 23:04 schrieb Pádraig Brady:
> On 21/07/18 13:36, Wodry wrote:
>> Am 21.07.2018 um 21:43 schrieb Pádraig Brady:
>>> We should update truncate(1) etc. to be consistent if making this change.
> 
> If you prepared a single patch to cover all, that would be great.
> Note also there is a shared note in coreutils.texi that reads:
> 
>   SIZE may be, or may be an integer optionally followed by,
>   one of the following multiplicative suffixes:
>           ‘KB’ =>           1000 (KiloBytes)
>           ‘K’  =>           1024 (KibiBytes)
>           ‘MB’ =>      1000*1000 (MegaBytes)
>           ‘M’  =>      1024*1024 (MebiBytes)
>           ‘GB’ => 1000*1000*1000 (GigaBytes)
>           ‘G’  => 1024*1024*1024 (GibiBytes)
>   and so on for ‘T’, ‘P’, ‘E’, ‘Z’, and ‘Y’.
> 
> There are individual notes on the options in the df man page etc.
> This needs to be carefully considered.
> Perhaps an additional note in the info docs is best for now?
> 
> cheers,
> Pádraig
> 
> 

I have considered all files that execute functions "xstrto*", excluding
xstrtod and xstrtold.
The fifth paramater ("valid_suffixes") of the xstrto* needs to contain a
'0' to be able to process binary prefixes.

I have considered all files that execute functions "xdectoint", which is
a wrapper vor xstrtol.
The fourth paramater ("suffixes") of this function needs to contain a
'0' to be able to process binary prefixes.

Here a matrix of my findings:

The following files can process Binary Prefixes:

file        proof command                        helptext type
----        -------------                        -------------
dd.c        echo hi | dd bs=1MiB                 own
df.c        df --block-size=1MiB /               emit_size_note
du.c        du --block-size=1MiB                 emit_size_note
head.c      : | head --lines=1KiB                own
ls.c        ls --block-size=1MiB                 emit_size_note
od.c        od --read-bytes=1KiB myfile          own
split.c     split --bytes=10KiB myfilec          emit_size_note
stdbuf.c    echo hi | stdbuf --output=1KiB cat   own
tail.c      : | tail --lines=1KiB                own
truncate.c  truncate --size=1MiB myfile          emit_size_note

In the patch attached (You can see it "live" also on
https://github.com/coreutils/coreutils/pull/15), I added a note to the
files own helptext (if it has that and does not execute emit_size_note),
and for the other commands only one time in the emit_size_note function.
As You suggested, I also added a note to doc/coreutils.texi.

I thought it would be clean, to have a simple change here, and only add
the same note everywhere, without changing the text that is already there.

The following files can not process Binary Prefixes:
chgrp.c
chroot.c
csplit.c
expr.c
extent-scan.c
install.c
join.c
md5sum.c
mknod.c
nice.c
numfmt.c        # uses two character binary prefixes like "Mi",
                #which is documneted in the man page. "MiB" is invalid
pr.c
ptx.c
shuf.c
shred.c
sort.c
stty.c
tr.c
uniq.c


Hope You like the patch and I did not have overseen something.


Best regards

docs-inform-about-binary-prefixes-in-helptexts.patch
Description: Text Data