#401939 od needs better default description

Package:
coreutils
Source:
coreutils
Description:
GNU core utilities
Submitter:
David Lawyer
Date:
2022-06-21 14:57:04 UTC
Severity:
minor
Tags:
#401939#5
Date:
2006-12-06 21:39:27 UTC
From:
To:
Here's the start of the od man page:

OD(1)                            User Commands                           OD(1)

NAME
       od - dump files in octal and other formats

SYNOPSIS
       od [OPTION]... [FILE]...
       od --traditional [FILE] [[+]OFFSET [[+]LABEL]]

DESCRIPTION
       Write an unambiguous representation, octal bytes by default, of FILE to
       standard output.  With more than one FILE argument, concatenate them in
       the  listed  order to form the input.  With no FILE, or when FILE is -,
       read standard input.
       [snip]
od (coreutils) 5.2.1            September 2005                           OD(1)
---------------------------------------------------------------------------
Now here's my test file: abcdefg

%od test gives:
0000000 061141 062143 063145 005147
0000010
%od -x test gives:
0000000 6261 6463 6665 0a67
0000010
%od -c test gives: 				//OK
0000000   a   b   c   d   e   f   g  \n
0000010
%hd test gives:					//OK
00000000  61 62 63 64 65 66 67 0a                           |abcdefg.|
00000008
-----------------------------------------------------------------------------
While the man says that od gives a representation of the bytes, the
first test only shows the values of the 2-byte words in octal.

The next test shows the values of the same words in hexadecimal.  Note
that that the value of the word is the value you get by swapping
bytes.  a b becomes b a, etc.  Checking the output of the first
example shows that it too has been byte-swapped.

The last 2 examples are OK.  The last example is for a different program
hd (hex-dump) which is outputting correctly.

Sure, od outputs the correct values of the words since the architecture
of the computer (actually of the Pentium CPU) is little endian (least
significant byte first).  But od is supposed to report byte values,
not word values.

			David Lawyer

#401939#10
Date:
2006-12-07 04:31:19 UTC
From:
To:
Please maintain the CC to both the bug number and the mailing list
when responding.  Thanks.

David Lawyer wrote:

Thanks for that report.  The documentation does appear to be in error,
or at least confusing, there.  The original v7 documentation said
this in the man page:

       Od dumps file in one or more formats as selected by the first
       argument.  If the first argument is missing, -o is default.
       The meanings of the format argument characters are:
       ...
       o  Interpret words in octal.

Later this was standardized by POSIX as:

http://www.opengroup.org/onlinepubs/009695399/utilities/od.html

  The od utility shall write the contents of its input files to
  standard output in a user-specified format.

  -o
    [XSI] [Option Start] Interpret words (two-byte units) in
    octal. This shall be equivalent to -t o2. [Option End]

  If no output type is specified, the default output shall be as if -t
  oS had been specified.

'S' is defined to be a "short".  The GNU help says:

       -o     same as -t o2, select octal shorts
       -x     same as -t x2, select hexadecimal shorts

Because of endian differences the byte printing order of shorts is
dependent upon the endianess of the system.  The GNU coreutils FAQ
lists this:

http://www.gnu.org/software/coreutils/faq/
  Search for "The 'od -x' command prints bytes in the wrong order."

  If you require a specific byte ordering, note bytes not words, then
  you need to supply a byte specification such as 'od -t x1'.

"ba" equates to 01100010 01100001 binary or 061141 octal.  And so on for
the others there.  So that appears correct to me.  If somewhat less
than useful in day to day use.  But that is the historical behavior.

By default shorts are printed in native byte ordering.  For portable
use the size option should always be given.  I recommend -tx1.

Yes.  This is the required behavior.

Thanks for reporting that documentation issue.  'od' is behaving
correctly according to traditional behavior and standards
conformance.  But I do think the online help should be updated.  Do
you have any suggestions for improved wording?

Thanks
Bob

#401939#15
Date:
2008-01-26 14:50:20 UTC
From:
To:
Command is behaving as expected, no documentation changes have been
proposed.

#401939#20
Date:
2008-01-26 19:50:38 UTC
From:
To:
This bug still exists.
Not so.  I just tried it again and got the same results with coreutils
5.97.

			David Lawyer

#401939#35
Date:
2008-01-29 03:56:35 UTC
From:
To:
Please maintain the CC to both the bug number and the mailing list
when responding.  Thanks.

David Lawyer wrote:

Did you see my previous response to your bug report?  It appears that
you did not for some reason.  You can read the exchange in the bug
database here:

http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=401939

Or in the mailing list archive here:

http://lists.gnu.org/archive/html/bug-coreutils/2006-12/msg00043.html

Yes.  That is the correct behavior.

That comment I am sure referred to the fact that no suggestions were
proposed to improve the upstream documentation.  Since there were no
suggestions proposed the bug was closed.  The results of the command
remain the same because the command is behaving correctly.

This has since been documented in the coreutils FAQ:

http://www.gnu.org/software/coreutils/faq/#The-_0027od-_002dx_0027-command-prints-bytes-in-the-wrong-order_002e

Hope this helps,
Bob

#401939#40
Date:
2021-10-12 11:07:06 UTC
From:
To:
Good day.

Have you viewed the report I sent? Kindly take a look, the previous message
might not arrived.

https://topccira.com/qui-consectetur/beatae.zip
-----Original Message-----
#401939#45
Date:
2022-06-21 14:46:34 UTC
From:
To: