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

From: Wodry <[email-masked]>
Date: Sun, 22 Jul 2018 15:57:37 +0200

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
>From 22a36ecc8b671cbeb2459aa7450db4368cd21f1b Mon Sep 17 00:00:00 2001
From: wodry <[email-masked]>
Date: Sat, 21 Jul 2018 19:45:07 +0200
Subject: [PATCH] Inform about binary prefixes in helptexts

---
 doc/coreutils.texi | 4 ++++
 src/dd.c           | 1 +
 src/f              | 0
 src/head.c         | 1 +
 src/od.c           | 1 +
 src/stdbuf.c       | 1 +
 src/system.h       | 1 +
 src/tail.c         | 1 +
 8 files changed, 10 insertions(+)
 create mode 100644 src/f

diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 10fd023d8..118fea9db 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -697,6 +697,8 @@ one of the following multiplicative suffixes:
 @samp{G}  => 1024*1024*1024 (GibiBytes)
 @end example
 and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
+Binary prefixes can be used, too: @samp{KiB} =@samp{K}, @samp{MiB} =@samp{M},
+@samp{GiB} =@samp{G}, and so on.
 @end macro
 
 @c FIXME: same as above, but no ``blocks'' line.
@@ -712,6 +714,8 @@ one of the following multiplicative suffixes:
 @samp{G}  => 1024*1024*1024 (GibiBytes)
 @end example
 and so on for @samp{T}, @samp{P}, @samp{E}, @samp{Z}, and @samp{Y}.
+Binary prefixes can be used, too: @samp{KiB} =@samp{K}, @samp{MiB} =@samp{M},
+@samp{GiB} =@samp{G}, and so on.
 @end macro
 
 @cindex common options
diff --git a/src/dd.c b/src/dd.c
index 70bbbb19e..68b059398 100644
--- a/src/dd.c
+++ b/src/dd.c
@@ -594,6 +594,7 @@ Copy a file, converting and formatting according to the operands.\n\
 N and BYTES may be followed by the following multiplicative suffixes:\n\
 c =1, w =2, b =512, kB =1000, K =1024, MB =1000*1000, M =1024*1024, xM =M,\n\
 GB =1000*1000*1000, G =1024*1024*1024, and so on for T, P, E, Z, Y.\n\
+Binary prefixes can be used, too: KiB =K, MiB =M, GiB =G, and so on.\n\
 \n\
 Each CONV symbol may be:\n\
 \n\
diff --git a/src/f b/src/f
new file mode 100644
index 000000000..e69de29bb
diff --git a/src/head.c b/src/head.c
index e1611778f..2c56e6d9e 100644
--- a/src/head.c
+++ b/src/head.c
@@ -141,6 +141,7 @@ With more than one FILE, precede each with a header giving the file name.\n\
 NUM may have a multiplier suffix:\n\
 b 512, kB 1000, K 1024, MB 1000*1000, M 1024*1024,\n\
 GB 1000*1000*1000, G 1024*1024*1024, and so on for T, P, E, Z, Y.\n\
+Binary prefixes can be used, too: KiB =K, MiB =M, GiB =G, and so on.\n\
 "), stdout);
       emit_ancillary_info (PROGRAM_NAME);
     }
diff --git a/src/od.c b/src/od.c
index 1a4aedee7..00e6b9ed8 100644
--- a/src/od.c
+++ b/src/od.c
@@ -417,6 +417,7 @@ BYTES is hex with 0x or 0X prefix, and may have a multiplier suffix:\n\
   MB   1000*1000\n\
   M    1024*1024\n\
 and so on for G, T, P, E, Z, Y.\n\
+Binary prefixes can be used, too: KiB =K, MiB =M, GiB =G, and so on.\n\
 "), stdout);
       emit_ancillary_info (PROGRAM_NAME);
     }
diff --git a/src/stdbuf.c b/src/stdbuf.c
index a212be3d0..11e3bf624 100644
--- a/src/stdbuf.c
+++ b/src/stdbuf.c
@@ -111,6 +111,7 @@ If MODE is '0' the corresponding stream will be unbuffered.\n\
       fputs (_("\n\
 Otherwise MODE is a number which may be followed by one of the following:\n\
 KB 1000, K 1024, MB 1000*1000, M 1024*1024, and so on for G, T, P, E, Z, Y.\n\
+Binary prefixes can be used, too: KiB =K, MiB =M, GiB =G, and so on.\n\
 In this case the corresponding stream will be fully buffered with the buffer\n\
 size set to MODE bytes.\n\
 "), stdout);
diff --git a/src/system.h b/src/system.h
index 4597d61aa..18416b4f2 100644
--- a/src/system.h
+++ b/src/system.h
@@ -595,6 +595,7 @@ emit_size_note (void)
   fputs (_("\n\
 The SIZE argument is an integer and optional unit (example: 10K is 10*1024).\n\
 Units are K,M,G,T,P,E,Z,Y (powers of 1024) or KB,MB,... (powers of 1000).\n\
+Binary prefixes can be used, too: KiB =K, MiB =M, GiB =G, and so on.\n\
 "), stdout);
 }
 
diff --git a/src/tail.c b/src/tail.c
index ac001d7c0..a5d9ef060 100644
--- a/src/tail.c
+++ b/src/tail.c
@@ -315,6 +315,7 @@ With more than one FILE, precede each with a header giving the file name.\n\
 NUM may have a multiplier suffix:\n\
 b 512, kB 1000, K 1024, MB 1000*1000, M 1024*1024,\n\
 GB 1000*1000*1000, G 1024*1024*1024, and so on for T, P, E, Z, Y.\n\
+Binary prefixes can be used, too: KiB =K, MiB =M, GiB =G, and so on.\n\
 \n\
 "), stdout);
      fputs (_("\
-- 
2.11.0