Re: Bug#401939: od dumps byte-swapped words instead of bytes

[Bob Proulx]

Please maintain the CC to both the bug number and the mailing list
when responding.  Thanks.

David Lawyer wrote:
>        Write an unambiguous representation, octal bytes by default,
>        of FILE to standard output.

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'.

> Now here's my test file: abcdefg
> 
> %od test gives:
> 0000000 061141 062143 063145 005147

"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.

> 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.

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

> 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.

Yes.  This is the required behavior.

> 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.

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