[PATCH] hexdump: adjust -s and -n option in the man page [was: hexsyntax.c using strtol on the offset parameter]

[PATCH] hexdump: adjust -s and -n option in the man page [was: hexsyntax.c using strtol on the offset parameter]

[Bernhard Voelker]

Karel Zak wrote:

> Fixed. The code (as well as -n) was stupid. Now it supports all
> possible suffixes (K,M,G,T,P,E,Y,Z) and the number is parsed as
> uintmax_t.

btw: it should read "...P,E,Z,Y", as Y>Z.

The man page is outdated now:

       -n length
              Interpret only length bytes of input.
       ...
       -s offset
              Skip  offset bytes from the beginning of the input.  By default,
              offset is interpreted as a decimal number.  With a leading 0x or
              0X,  offset  is  interpreted as a hexadecimal number, otherwise,
              with a leading 0, offset is  interpreted  as  an  octal  number.
              Appending  the  character  b,  k, or m to offset causes it to be
              interpreted as a multiple of  512,  1024,  or  1048576,  respec-
              tively.

The variant with 0x or 0X doesn't seem to work anyway:

$ echo 123456789abcdefghijk > /tmp/x
$ text-utils/hexdump -s 0x1 -n 1 -c /tmp/x
0000001   2
0000002

Below follows a proposal for a man page patch.

Have a nice day,
Berny

>From f546c9d7bdd52b2e57761c2c97a701e662d89bc1 Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <mail@bernhard-voelker.de>
Date: Thu, 22 Mar 2012 12:53:06 +0100
Subject: [PATCH] hexdump: adjust -s and -n option in the man page

Remove note about hexadecimal and octal interpretation of -s value.
Mention the optional suffix notation for -n and -s  like <x>B or <x>iB
with <x> in K,M,G,T,P,E,Z,Y.

Signed-off-by: Bernhard Voelker <mail@bernhard-voelker.de>
---
 text-utils/hexdump.1 |   33 +++++++++------------------------
 1 files changed, 9 insertions(+), 24 deletions(-)

diff --git a/text-utils/hexdump.1 b/text-utils/hexdump.1
index cbb14fb..4a373de 100644
--- a/text-utils/hexdump.1
+++ b/text-utils/hexdump.1
@@ -80,7 +80,8 @@ are ignored.
 .BI \-n \ length
 Interpret only
 .I length
-bytes of input.
+.B BYTES
+of input.
 .TP
 .B \-o
 \fITwo-byte octal display\fR.  Display the input offset in hexadecimal,
@@ -90,29 +91,8 @@ quantities of input data, in octal, per line.
 .BI \-s \ offset
 Skip
 .I offset
-bytes from the beginning of the input.  By default,
-.I offset
-is interpreted as a decimal number.  With a leading
-.B 0x
-or
-.BR 0X ,
-.I offset
-is interpreted as a hexadecimal number, otherwise, with a leading
-.BR 0 ,
-.I offset
-is interpreted as an octal number.  Appending the character
-.BR b ,
-.BR k ,
-or
-.B m
-to
-.I offset
-causes it to be interpreted as a multiple of
-.IR 512 ,
-.IR 1024 ,
-or
-.IR 1048576 ,
-respectively.
+.B BYTES
+from the beginning of the input.
 .TP
 .B \-v
 The
@@ -138,6 +118,11 @@ according to the format strings specified by the
 and
 .B \-f
 options, in the order that they were specified.
+.PP
+.B BYTES
+is a decimal number and may be followed by the following multiplicative
+suffixes: KB =1000, KiB =1024, MB =1000*1000, MiB =1024*1024,
+GB =1000*1000*1000, GiB =1024*1024*1024, and so on for T, P, E, Z, Y.
 .SH FORMATS
 A format string contains any number of format units, separated by whitespace.
 A format unit contains up to three items: an iteration count, a byte count,
-- 
1.7.7

Re: [PATCH] hexdump: adjust -s and -n option in the man page [was: hexsyntax.c using strtol on the offset parameter]

[Karel Zak]

On Thu, Mar 22, 2012 at 12:58:49PM +0100, Bernhard Voelker wrote:
> Karel Zak wrote:
> 
> > Fixed. The code (as well as -n) was stupid. Now it supports all
> > possible suffixes (K,M,G,T,P,E,Y,Z) and the number is parsed as
> > uintmax_t.
> 
> btw: it should read "...P,E,Z,Y", as Y>Z.
> 
> The man page is outdated now:
> 
>        -n length
>               Interpret only length bytes of input.
>        ...
>        -s offset
>               Skip  offset bytes from the beginning of the input.  By default,
>               offset is interpreted as a decimal number.  With a leading 0x or
>               0X,  offset  is  interpreted as a hexadecimal number, otherwise,
>               with a leading 0, offset is  interpreted  as  an  octal  number.
>               Appending  the  character  b,  k, or m to offset causes it to be
>               interpreted as a multiple of  512,  1024,  or  1048576,  respec-
>               tively.
> 
> The variant with 0x or 0X doesn't seem to work anyway:
> 
> $ echo 123456789abcdefghijk > /tmp/x
> $ text-utils/hexdump -s 0x1 -n 1 -c /tmp/x
> 0000001   2
> 0000002

 offset addressed by 0x works for me:

./text-utils/hexdump -s 0x1fe -n 2 /dev/sda
00001fe aa55                                   
0000200


> From f546c9d7bdd52b2e57761c2c97a701e662d89bc1 Mon Sep 17 00:00:00 2001
> From: Bernhard Voelker <mail@bernhard-voelker.de>
> Date: Thu, 22 Mar 2012 12:53:06 +0100
> Subject: [PATCH] hexdump: adjust -s and -n option in the man page

 Good point, I have copied the text we already have in the losetup man
 page.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH] hexdump: adjust -s and -n option in the man page [was: hexsyntax.c using strtol on the offset parameter]

[mail]

 Karel Zak wrote:
> > From: Bernhard Voelker <mail@bernhard-voelker.de>
> > Date: Thu, 22 Mar 2012 12:53:06 +0100
> > Subject: [PATCH] hexdump: adjust -s and -n option in the man page
>
> Good point, I have copied the text we already have in the losetup man
> page.
>
> +The \fIlength\fR and \fIoffset\fR arguments may be followed by binary
(2^N)
> +suffixes KiB, MiB, GiB, TiB, PiB and EiB (the "iB" is optional, e.g. "K"
has the
> +same meaning as "KiB") or decimal (10^N) suffixes KB, MB, GB, PB and EB.

Thanks.

I have derived my patch proposal from the info pages of coreutils, as there
has recently been a discussion about the clearest wording.
I don't think all users are aware what's the difference between
"binary (2^N) suffixes KiB" and "decimal (10^N) suffixes KB".

BTW: why omitting the Z and the Y suffix in the man page?

Have a nice day, Berny

Re: [PATCH] hexdump: adjust -s and -n option in the man page [was: hexsyntax.c using strtol on the offset parameter]

[Karel Zak]

 Hi Berny,

On Mon, Mar 26, 2012 at 09:20:26AM +0200, mail@bernhard-voelker.de wrote:
> I have derived my patch proposal from the info pages of coreutils, as there
> has recently been a discussion about the clearest wording.
> I don't think all users are aware what's the difference between
> "binary (2^N) suffixes KiB" and "decimal (10^N) suffixes KB".

hmm, good point, send patch that fix the problem in all the man pages.

> BTW: why omitting the Z and the Y suffix in the man page?

Send patch ;-)

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH] hexdump: adjust -s and -n option in the man page [was: hexsyntax.c using strtol on the offset parameter]

[mail]

[-- Attachment #1: Type: text/plain, Size: 720 bytes --]

 On March 26, 2012 at 10:42 AM Karel Zak <kzak@redhat.com> wrote:

> Hi Berny,
> 
> > On Mon, Mar 26, 2012 at 09:20:26AM +0200, mail@bernhard-voelker.de
wrote:
> > I have derived my patch proposal from the info pages of coreutils, as
there
> > has recently been a discussion about the clearest wording.
> > I don't think all users are aware what's the difference between
> > "binary (2^N) suffixes KiB" and "decimal (10^N) suffixes KB".
> 
> hmm, good point, send patch that fix the problem in all the man pages.
> 
> > BTW: why omitting the Z and the Y suffix in the man page?
> Send patch ;-)

Attached:

* [PATCH 1/2] wipefs: use strtosize() for -o
* [PATCH 2/2] docs: clarify KiB vs. KB in man pages

Have fun,
Berny

[-- Attachment #2: strtosize-man.patch --]
[-- Type: application/octet-stream, Size: 7547 bytes --]

From f61110adcceaecee78c78f40f02504b5c2aacb56 Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <mail@bernhard-voelker.de>
Date: Mon, 26 Mar 2012 11:23:12 +0200
Subject: [PATCH 1/2] wipefs: use strtosize() for -o

Signed-off-by: Bernhard Voelker <mail@bernhard-voelker.de>
---
 misc-utils/wipefs.c |    8 ++++++--
 1 files changed, 6 insertions(+), 2 deletions(-)

diff --git a/misc-utils/wipefs.c b/misc-utils/wipefs.c
index 74de3a3..3681fee 100644
--- a/misc-utils/wipefs.c
+++ b/misc-utils/wipefs.c
@@ -385,6 +385,7 @@ main(int argc, char **argv)
 {
 	struct wipe_desc *wp0 = NULL, *wp;
 	int c, all = 0, has_offset = 0, noact = 0, mode = 0, quiet = 0;
+	uintmax_t offset;
 
 	static const struct option longopts[] = {
 	    { "all",       0, 0, 'a' },
@@ -413,8 +414,11 @@ main(int argc, char **argv)
 		case 'n':
 			noact++;
 			break;
-		case 'o':
-			wp0 = add_offset(wp0, strtoll_offset(optarg), 1);
+		case 'o': {
+			if (strtosize(optarg, &offset)
+				errx(EXIT_FAILURE,
+				     _("invalid offset '%s' specified"), optarg);
+			wp0 = add_offset(wp0, offset, 1);
 			has_offset++;
 			break;
 		case 'p':
-- 
1.7.9


From f5956cee4c7e6d57a0fe00af2937617d698adbd9 Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <mail@bernhard-voelker.de>
Date: Mon, 26 Mar 2012 11:30:16 +0200
Subject: [PATCH 2/2] docs: clarify KiB vs. KB in man pages

Update the man pages of blkid, wipefs, fallocate, fstrim, losetup
and hexdump to clarify the suffixes for the numerical values of the
offset and size/length arguments regarding KiB=1024 vs KB=1000.
Also mention the ZiB/YiB and ZB/YB suffixes supported by strtosize().

Signed-off-by: Bernhard Voelker <mail@bernhard-voelker.de>
---
 misc-utils/blkid.8    |    7 ++++---
 misc-utils/wipefs.8   |    7 ++++---
 sys-utils/fallocate.1 |    7 ++++---
 sys-utils/fstrim.8    |    7 ++++---
 sys-utils/losetup.8   |    7 ++++---
 text-utils/hexdump.1  |    7 ++++---
 6 files changed, 24 insertions(+), 18 deletions(-)

diff --git a/misc-utils/blkid.8 b/misc-utils/blkid.8
index c8a3121..80363ac 100644
--- a/misc-utils/blkid.8
+++ b/misc-utils/blkid.8
@@ -69,9 +69,10 @@ has two main forms of operation: either searching for a device with a
 specific NAME=value pair, or displaying NAME=value pairs for one or
 more specified devices.
 .SH OPTIONS
-The \fIsize\fR and \fIoffset\fR arguments may be followed by binary (2^N) 
-suffixes KiB, MiB, GiB, TiB, PiB and EiB (the "iB" is optional, e.g. "K" has the
-same meaning as "KiB") or decimal (10^N) suffixes KB, MB, GB, PB and EB.
+The \fIsize\fR and \fIoffset\fR arguments may be followed by the multiplicative
+suffixes KiB=1024, MiB=1024*1024, and so on for GiB, TiB, PiB, EiB, ZiB and YiB
+(the "iB" is optional, e.g. "K" has the same meaning as "KiB") or the suffixes 
+KB=1000, MB=1000*1000, and so on for GB, PB, EB, ZB and YB.
 .TP
 .BI \-c " cachefile"
 Read from
diff --git a/misc-utils/wipefs.8 b/misc-utils/wipefs.8
index cee8ef7..85d9576 100644
--- a/misc-utils/wipefs.8
+++ b/misc-utils/wipefs.8
@@ -47,9 +47,10 @@ Specify the location (in bytes) of the signature which should be erased from the
 device.  The \fIoffset\fR number may include a "0x" prefix; then the number will be
 interpreted as a hex value.  It is possible to specify multiple \fB-o\fR options.
 
-The \fIoffset\fR argument may be followed by binary (2^N) suffixes KiB, MiB,
-GiB, TiB, PiB and EiB (the "iB" is optional, e.g. "K" has the same meaning as
-"KiB") or decimal (10^N) suffixes KB, MB, GB, PB and EB.
+The \fIoffset\fR argument may be followed by the multiplicative
+suffixes KiB=1024, MiB=1024*1024, and so on for GiB, TiB, PiB, EiB, ZiB and YiB
+(the "iB" is optional, e.g. "K" has the same meaning as "KiB") or the suffixes 
+KB=1000, MB=1000*1000, and so on for GB, PB, EB, ZB and YB.
 .IP "\fB\-p, \-\-parsable\fP"
 Print out in parsable instead of printable format.  Encode all potentially unsafe
 characters of a string to the corresponding hex value prefixed by '\\x'.
diff --git a/sys-utils/fallocate.1 b/sys-utils/fallocate.1
index 653ebfb..a6eae8f 100644
--- a/sys-utils/fallocate.1
+++ b/sys-utils/fallocate.1
@@ -26,9 +26,10 @@ The exit code returned by
 is 0 on success and 1 on failure.
 .PP
 .SH OPTIONS
-The \fIlength\fR and \fIoffset\fR arguments may be followed by binary (2^N)
-suffixes KiB, MiB, GiB, TiB, PiB and EiB (the "iB" is optional, e.g. "K" has the
-same meaning as "KiB") or decimal (10^N) suffixes KB, MB, GB, PB and EB.
+The \fIlength\fR and \fIoffset\fR arguments may be followed by the multiplicative
+suffixes KiB=1024, MiB=1024*1024, and so on for GiB, TiB, PiB, EiB, ZiB and YiB
+(the "iB" is optional, e.g. "K" has the same meaning as "KiB") or the suffixes 
+KB=1000, MB=1000*1000, and so on for GB, PB, EB, ZB and YB.
 .IP "\fB\-n, \-\-keep-size\fP"
 Do not modify the apparent length of the file.  This may effectively allocate
 blocks past EOF, which can be removed with a truncate.
diff --git a/sys-utils/fstrim.8 b/sys-utils/fstrim.8
index 18b5eaf..a235703 100644
--- a/sys-utils/fstrim.8
+++ b/sys-utils/fstrim.8
@@ -31,9 +31,10 @@ is mounted.
 
 .SH OPTIONS
 The \fIoffset\fR, \fIlength\fR, and \fIminimum-free-extent\fR arguments may be
-followed by binary (2^N) suffixes KiB, MiB, GiB, TiB, PiB and EiB (the "iB" is
-optional, e.g. "K" has the same meaning as "KiB") or decimal (10^N) suffixes
-KB, MB, GB, PB and EB.
+followed by the multiplicative suffixes KiB=1024, MiB=1024*1024, and so on for
+GiB, TiB, PiB, EiB, ZiB and YiB (the "iB" is optional, e.g. "K" has the same
+meaning as "KiB") or the suffixes KB=1000, MB=1000*1000, and so on for GB, PB,
+EB, ZB and YB.
 .IP "\fB\-h, \-\-help\fP"
 Print help and exit.
 .IP "\fB\-o, \-\-offset\fP \fIoffset\fP"
diff --git a/sys-utils/losetup.8 b/sys-utils/losetup.8
index f50b072..fd16cff 100644
--- a/sys-utils/losetup.8
+++ b/sys-utils/losetup.8
@@ -69,9 +69,10 @@ to detach loop devices and to query the status of a loop device. If only the
 device is shown.
 
 .SH OPTIONS
-The \fIsize\fR and \fIoffset\fR arguments may be followed by binary (2^N)
-suffixes KiB, MiB, GiB, TiB, PiB and EiB (the "iB" is optional, e.g. "K" has the
-same meaning as "KiB") or decimal (10^N) suffixes KB, MB, GB, PB and EB.
++The \fIsize\fR and \fIoffset\fR arguments may be followed by the multiplicative
++suffixes KiB=1024, MiB=1024*1024, and so on for GiB, TiB, PiB, EiB, ZiB and YiB
++(the "iB" is optional, e.g. "K" has the same meaning as "KiB") or the suffixes 
++KB=1000, MB=1000*1000, and so on for GB, PB, EB, ZB and YB.
 
 .IP "\fB\-a, \-\-all\fP"
 show status of all loop devices. Note that not all information are accessible
diff --git a/text-utils/hexdump.1 b/text-utils/hexdump.1
index 0b3a525..84ecaf4 100644
--- a/text-utils/hexdump.1
+++ b/text-utils/hexdump.1
@@ -44,9 +44,10 @@ utility is a filter which displays the specified files, or
 standard input if no files are specified, in a user-specified
 format.
 .SH OPTIONS
-The \fIlength\fR and \fIoffset\fR arguments may be followed by binary (2^N)
-suffixes KiB, MiB, GiB, TiB, PiB and EiB (the "iB" is optional, e.g. "K" has the
-same meaning as "KiB") or decimal (10^N) suffixes KB, MB, GB, PB and EB.
+The \fIlength\fR and \fIoffset\fR arguments may be followed by the multiplicative
+suffixes KiB=1024, MiB=1024*1024, and so on for GiB, TiB, PiB, EiB, ZiB and YiB
+(the "iB" is optional, e.g. "K" has the same meaning as "KiB") or the suffixes
+KB=1000, MB=1000*1000, and so on for GB, PB, EB, ZB and YB.
 .TP
 .B \-b
 \fIOne-byte octal display\fR.  Display the input offset in hexadecimal,
-- 
1.7.9

Re: [PATCH] hexdump: adjust -s and -n option in the man page [was: hexsyntax.c using strtol on the offset parameter]

[mail]

On March 26, 2012 at 11:39 AM "mail@bernhard-voelker.de"
<mail@bernhard-voelker.de> wrote:

> * [PATCH 1/2] wipefs: use strtosize() for -o


oops, sorry, there is an error in that patch.
It was obviously not so trivial as at seemed to be.

Here's the correction.

Berny

>From 531cb1ec623fc5c3ac0e95f897b712517b5b1167 Mon Sep 17 00:00:00 2001
From: Bernhard Voelker <mail@bernhard-voelker.de>
Date: Mon, 26 Mar 2012 11:48:57 +0200
Subject: [PATCH] wipefs: use strtosize() for -o
Signed-off-by: Bernhard Voelker <mail@bernhard-voelker.de>
---
misc-utils/wipefs.c | 6 +++++-
1 files changed, 5 insertions(+), 1 deletions(-)
diff --git a/misc-utils/wipefs.c b/misc-utils/wipefs.c
index 74de3a3..5059c7c 100644
--- a/misc-utils/wipefs.c
+++ b/misc-utils/wipefs.c
@@ -385,6 +385,7 @@ main(int argc, char **argv)
{
struct wipe_desc *wp0 = NULL, *wp;
int c, all = 0, has_offset = 0, noact = 0, mode = 0, quiet = 0;
+ uintmax_t offset;

static const struct option longopts[] = {
{ "all", 0, 0, 'a' },
@@ -414,7 +415,10 @@ main(int argc, char **argv)
noact++;
break;
case 'o':
- wp0 = add_offset(wp0, strtoll_offset(optarg), 1);
+ if (strtosize(optarg, &offset))
+ errx(EXIT_FAILURE,
+ _("invalid offset '%s' specified"), optarg);
+ wp0 = add_offset(wp0, offset, 1);
has_offset++;
break;
case 'p':
--
1.7.9

Re: [PATCH] hexdump: adjust -s and -n option in the man page [was: hexsyntax.c using strtol on the offset parameter]

[Karel Zak]

On Mon, Mar 26, 2012 at 11:39:46AM +0200, mail@bernhard-voelker.de wrote:

> * [PATCH 2/2] docs: clarify KiB vs. KB in man pages

 Applied, thanks.

    Karel


-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com

Re: [PATCH] hexdump: adjust -s and -n option in the man page [was: hexsyntax.c using strtol on the offset parameter]

[Karel Zak]

On Mon, Mar 26, 2012 at 11:50:06AM +0200, mail@bernhard-voelker.de wrote:
> 
> On March 26, 2012 at 11:39 AM "mail@bernhard-voelker.de"
> <mail@bernhard-voelker.de> wrote:
> 
> > * [PATCH 1/2] wipefs: use strtosize() for -o
> 
> 
> oops, sorry, there is an error in that patch.
> It was obviously not so trivial as at seemed to be.
> 
> Here's the correction.
> 
> Berny
> 
> From 531cb1ec623fc5c3ac0e95f897b712517b5b1167 Mon Sep 17 00:00:00 2001
> From: Bernhard Voelker <mail@bernhard-voelker.de>
> Date: Mon, 26 Mar 2012 11:48:57 +0200
> Subject: [PATCH] wipefs: use strtosize() for -o
> Signed-off-by: Bernhard Voelker <mail@bernhard-voelker.de>
> ---
> misc-utils/wipefs.c | 6 +++++-
> 1 files changed, 5 insertions(+), 1 deletions(-)
> diff --git a/misc-utils/wipefs.c b/misc-utils/wipefs.c
> index 74de3a3..5059c7c 100644
> --- a/misc-utils/wipefs.c
> +++ b/misc-utils/wipefs.c
> @@ -385,6 +385,7 @@ main(int argc, char **argv)
> {
> struct wipe_desc *wp0 = NULL, *wp;
> int c, all = 0, has_offset = 0, noact = 0, mode = 0, quiet = 0;
> + uintmax_t offset;
> 
> static const struct option longopts[] = {
> { "all", 0, 0, 'a' },
> @@ -414,7 +415,10 @@ main(int argc, char **argv)
> noact++;
> break;
> case 'o':
> - wp0 = add_offset(wp0, strtoll_offset(optarg), 1);

 strtoll_offset() uses strtosize() :-)

 Anyway, I'll add strtosize_or_err() to make it more usable in
 argv[] parsers.

    Karel

-- 
 Karel Zak  <kzak@redhat.com>
 http://karelzak.blogspot.com