GNU bug report logs - #32242
dd help text lacks information about binary prefixes

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 32242 in the body.
You can then email your comments to 32242 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Wodry <coreutils3422 <at> runbox.com>
To: bug-coreutils <at> gnu.org
Subject: dd help text lacks information about binary prefixes
Date: Sat, 21 Jul 2018 20:48:37 +0200

[Message part 1 (text/plain, inline)]

One can use binary prefixes (iB, e.g. MiB) with dd command, but that is
not written in the help text.

I just found out because I wanted to add support for binary prefixes
since I did not know they are already supported.

It's a hidden, but valuable feature, since I think, that M is binary is
hard to remember and can easily lead to confusion.

Much clearer is to use MiB. "M" is mentioned only for backwards
compatibility in this patch.

The parsing for binary prefixes is done in

gnulib/lib/xstrtol.c

so this is not dd specific.

[dd-inform-about-binary-prefixes-in-helptext.patch (text/x-patch, attachment)]

Message #8 received at 32242 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Wodry <coreutils3422 <at> runbox.com>, 32242 <at> debbugs.gnu.org
Subject: Re: bug#32242: dd help text lacks information about binary prefixes
Date: Sat, 21 Jul 2018 12:43:12 -0700

On 21/07/18 11:48, Wodry wrote:
> One can use binary prefixes (iB, e.g. MiB) with dd command, but that is
> not written in the help text.
> 
> I just found out because I wanted to add support for binary prefixes
> since I did not know they are already supported.
> 
> It's a hidden, but valuable feature, since I think, that M is binary is
> hard to remember and can easily lead to confusion.
> 
> Much clearer is to use MiB. "M" is mentioned only for backwards
> compatibility in this patch.
> 
> The parsing for binary prefixes is done in
> 
> gnulib/lib/xstrtol.c
> 
> so this is not dd specific.

MiB is less ambiguous to read, though somewhat less portable.
We should update truncate(1) etc. to be consistent if making this change.

thanks,
Pádraig

Message #11 received at 32242 <at> debbugs.gnu.org (full text, mbox):

From: Wodry <coreutils3422 <at> runbox.com>
To: 32242 <at> debbugs.gnu.org
Subject: Re: bug#32242: Acknowledgement (dd help text lacks information about
 binary prefixes)
Date: Sat, 21 Jul 2018 21:51:45 +0200

[Message part 1 (text/plain, inline)]

Thare was a typo.

Old: K=KiB
New: K =KiB

New patch attached.




Am 21.07.2018 um 21:17 schrieb GNU bug Tracking System:
> Thank you for filing a new bug report with debbugs.gnu.org.
> 
> This is an automatically generated reply to let you know your message
> has been received.
> 
> Your message is being forwarded to the package maintainers and other
> interested parties for their attention; they will reply in due course.
> 
> Your message has been sent to the package maintainer(s):
>  bug-coreutils <at> gnu.org
> 
> If you wish to submit further information on this problem, please
> send it to 32242 <at> debbugs.gnu.org.
> 
> Please do not send mail to help-debbugs <at> gnu.org unless you wish
> to report a problem with the Bug-tracking system.
> 

[dd-inform-about-binary-prefixes-in-helptext.2.patch (text/x-patch, attachment)]

Message #14 received at 32242 <at> debbugs.gnu.org (full text, mbox):

From: Wodry <coreutils3422 <at> runbox.com>
To: Pádraig Brady <P <at> draigBrady.com>, 32242 <at> debbugs.gnu.org
Subject: Re: bug#32242: dd help text lacks information about binary prefixes
Date: Sat, 21 Jul 2018 22:16:27 +0200

Am 21.07.2018 um 21:43 schrieb Pádraig Brady:
> We should update truncate(1) etc. to be consistent if making this change

+1

Message #17 received at 32242 <at> debbugs.gnu.org (full text, mbox):

From: Wodry <coreutils3422 <at> runbox.com>
To: Pádraig Brady <P <at> draigBrady.com>, 32242 <at> debbugs.gnu.org
Subject: Re: bug#32242: dd help text lacks information about binary prefixes
Date: Sat, 21 Jul 2018 22:36:09 +0200

Am 21.07.2018 um 21:43 schrieb Pádraig Brady:
> We should update truncate(1) etc. to be consistent if making this change.

truncate uses function emit_size_note for size help text, as do:

git/coreutils/src$ grep -r emit_size_note

system.h:emit_size_note (void)
truncate.c:      emit_size_note ();
split.c:      emit_size_note ();
ls.c:      emit_size_note ();
du.c:      emit_size_note ();
df.c:      emit_size_note ();

So I would suggest to enhance the help text in function emit_size_note
in system.h

Maybe dd could also use emit_size_note?

Should I create a patch (in a seperate bug report) for emit_size_note,
or do You want to do that?

Best regards,

Wodry

Message #20 received at 32242 <at> debbugs.gnu.org (full text, mbox):

From: Pádraig Brady <P <at> draigBrady.com>
To: Wodry <coreutils3422 <at> runbox.com>, 32242 <at> debbugs.gnu.org
Subject: Re: bug#32242: dd help text lacks information about binary prefixes
Date: Sat, 21 Jul 2018 14:04:10 -0700

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.
> 
> truncate uses function emit_size_note for size help text, as do:
> 
> git/coreutils/src$ grep -r emit_size_note
> 
> system.h:emit_size_note (void)
> truncate.c:      emit_size_note ();
> split.c:      emit_size_note ();
> ls.c:      emit_size_note ();
> du.c:      emit_size_note ();
> df.c:      emit_size_note ();
> 
> So I would suggest to enhance the help text in function emit_size_note
> in system.h
> 
> Maybe dd could also use emit_size_note?
> 
> Should I create a patch (in a seperate bug report) for emit_size_note,
> or do You want to do that?

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

Message #23 received at 32242 <at> debbugs.gnu.org (full text, mbox):

From: Wodry <coreutils3422 <at> runbox.com>
To: Pádraig Brady <P <at> draigBrady.com>, 32242 <at> debbugs.gnu.org
Subject: Re: bug#32242: dd help text lacks information about binary prefixes
Date: Sun, 22 Jul 2018 15:57:37 +0200

[Message part 1 (text/plain, inline)]

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 (text/x-patch, attachment)]

Message #26 received at 32242 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Wodry <coreutils3422 <at> runbox.com>, Pádraig Brady
 <P <at> draigBrady.com>, 32242 <at> debbugs.gnu.org
Subject: Re: bug#32242: dd help text lacks information about binary prefixes
Date: Sun, 22 Jul 2018 07:04:43 -0700

Thanks, this looks good, except I'd omit the space before the equal sign, e.g., 
"KiB=K" rather than "KiB =K". It looks odd to have unequal spacing around "=".

Message #29 received at 32242 <at> debbugs.gnu.org (full text, mbox):

From: Wodry <coreutils3422 <at> runbox.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>, Pádraig Brady
 <P <at> draigBrady.com>, 32242 <at> debbugs.gnu.org
Subject: Re: bug#32242: dd help text lacks information about binary prefixes
Date: Sun, 22 Jul 2018 16:42:12 +0200

[Message part 1 (text/plain, inline)]

Great, nice to hear :)

I did also not like the space, but took it over from the source code of
dd.c. But it looks like this is the only file where this space occurs.

LANG=en_EN.utf8 dd --help

outputs

N and BYTES may be followed by the following multiplicative suffixes:
c =1, w =2, b =512, kB =1000, K =1024, MB =1000*1000, M =1024*1024, xM =M,

But in the translation there is no space:

LANG=de_DE.utf8 dd --help

outputs

N und BYTES können folgende multiplikative Endungen tragen:
c=1, w=2, b=512, kB=1000, K=1024, MB=1000×1000, M=1024×1024, xM=M


In the attached updated patch file I removed the space in the new
addtional notes and in the dd help text.

Best regards



Am 22.07.2018 um 16:04 schrieb Paul Eggert:
> Thanks, this looks good, except I'd omit the space before the equal
> sign, e.g., "KiB=K" rather than "KiB =K". It looks odd to have unequal
> spacing around "=".
> 
> 

[docs-inform-about-binary-prefixes-in-helptexts.2.patch (text/x-patch, attachment)]

Message #34 received at 32242-done <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Wodry <coreutils3422 <at> runbox.com>, Pádraig Brady
 <P <at> draigBrady.com>, 32242-done <at> debbugs.gnu.org
Subject: Re: bug#32242: dd help text lacks information about binary prefixes
Date: Sun, 22 Jul 2018 08:38:36 -0700

Thanks, I squashed all that together, removed the "GiB=G" part (two examples are 
enough), and installed it in your name. Closing the bug.

Message #37 received at 32242-done <at> debbugs.gnu.org (full text, mbox):

From: Wodry <coreutils3422 <at> runbox.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>, Pádraig Brady
 <P <at> draigBrady.com>, 32242-done <at> debbugs.gnu.org
Subject: Re: bug#32242: dd help text lacks information about binary prefixes
Date: Sun, 22 Jul 2018 18:14:28 +0200

That's great, I feel lucky to have been contributing to GNU core
utilities (the first time)!

Best regards

Am 22.07.2018 um 17:38 schrieb Paul Eggert:
> Thanks, I squashed all that together, removed the "GiB=G" part (two
> examples are enough), and installed it in your name. Closing the bug.
> 
> 

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.