The Open Group Base Specifications Issue 6
IEEE Std 1003.1, 2004 Edition
Copyright © 2001-2004 The IEEE and The Open Group, All Rights reserved.

NAME

od - dump files in various formats

SYNOPSIS

od [-v][-A address_base][-j skip][-N count][-t type_string]...
      
[file...]

[XSI] [Option Start] od [-bcdosx][file] [[+]offset[.][b]][Option End]

DESCRIPTION

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

OPTIONS

The od utility shall conform to the Base Definitions volume of IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines, except that the order of presentation of the -t options [XSI] [Option Start]  and the -bcdosx options [Option End] is significant.

The following options shall be supported:

-A  address_base
Specify the input offset base. See the EXTENDED DESCRIPTION section. The application shall ensure that the address_base option-argument is a character. The characters 'd', 'o', and 'x' specify that the offset base shall be written in decimal, octal, or hexadecimal, respectively. The character 'n' specifies that the offset shall not be written.
-b
[XSI] [Option Start] Interpret bytes in octal. This shall be equivalent to -t o1. [Option End]
-c
[XSI] [Option Start] Interpret bytes as characters specified by the current setting of the LC_CTYPE category. Certain non-graphic characters appear as C escapes: "NUL=\0", "BS=\b", "FF=\f", "NL=\n", "CR=\r", "HT=\t" ; others appear as 3-digit octal numbers. [Option End]
-d
[XSI] [Option Start] Interpret words (two-byte units) in unsigned decimal. This shall be equivalent to -t u2. [Option End]
-j  skip
Jump over skip bytes from the beginning of the input. The od utility shall read or seek past the first skip bytes in the concatenated input files. If the combined input is not at least skip bytes long, the od utility shall write a diagnostic message to standard error and exit with a non-zero exit status.

By default, the skip option-argument shall be interpreted as a decimal number. With a leading 0x or 0X, the offset shall be interpreted as a hexadecimal number; otherwise, with a leading '0', the offset shall be interpreted as an octal number. Appending the character 'b', 'k', or 'm' to offset shall cause it to be interpreted as a multiple of 512, 1024, or 1048576 bytes, respectively. If the skip number is hexadecimal, any appended 'b' shall be considered to be the final hexadecimal digit.

-N  count
Format no more than count bytes of input. By default, count shall be interpreted as a decimal number. With a leading 0x or 0X, count shall be interpreted as a hexadecimal number; otherwise, with a leading '0', it shall be interpreted as an octal number. If count bytes of input (after successfully skipping, if -j skip is specified) are not available, it shall not be considered an error; the od utility shall format the input that is available.
-o
[XSI] [Option Start] Interpret words (two-byte units) in octal. This shall be equivalent to -t o2. [Option End]
-s
[XSI] [Option Start] Interpret words (two-byte units) in signed decimal. This shall be equivalent to -t d2. [Option End]
-t  type_string
Specify one or more output types. See the EXTENDED DESCRIPTION section. The application shall ensure that the type_string option-argument is a string specifying the types to be used when writing the input data. The string shall consist of the type specification characters a, c, d, f, o, u, and x, specifying named character, character, signed decimal, floating point, octal, unsigned decimal, and hexadecimal, respectively. The type specification characters d, f, o, u, and x can be followed by an optional unsigned decimal integer that specifies the number of bytes to be transformed by each instance of the output type. The type specification character f can be followed by an optional F, D, or L indicating that the conversion should be applied to an item of type float, double, or long double, respectively. The type specification characters d, o, u, and x can be followed by an optional C, S, I, or L indicating that the conversion should be applied to an item of type char, short, int, or long, respectively. Multiple types can be concatenated within the same type_string and multiple -t options can be specified. Output lines shall be written for each type specified in the order in which the type specification characters are specified.
-v
Write all input data. Without the -v option, any number of groups of output lines, which would be identical to the immediately preceding group of output lines (except for the byte offsets), shall be replaced with a line containing only an asterisk ( '*' ).
-x
[XSI] [Option Start] Interpret words (two-byte units) in hexadecimal. This shall be equivalent to -t x2. [Option End]

[XSI] [Option Start] Multiple types can be specified by using multiple -bcdostx options. Output lines are written for each type specified in the order in which the types are specified. [Option End]

OPERANDS

The following operands shall be supported:

file
A pathname of a file to be read. If no file operands are specified, the standard input shall be used.

If there are no more than two operands, none of the -A, -j, -N, or -t options is specified, and either of the following is true: the first character of the last operand is a plus sign ( '+' ), or there are two operands and the first character of the last operand is numeric; [XSI] [Option Start]  the last operand shall be interpreted as an offset operand on XSI-conformant systems. [Option End] Under these conditions, the results are unspecified on systems that are not XSI-conformant systems.

[+]offset[.][b]
[XSI] [Option Start] The offset operand specifies the offset in the file where dumping is to commence. This operand is normally interpreted as octal bytes. If '.' is appended, the offset shall be interpreted in decimal. If 'b' is appended, the offset shall be interpreted in units of 512 bytes. [Option End]

STDIN

The standard input shall be used only if no file operands are specified. See the INPUT FILES section.

INPUT FILES

The input files can be any file type.

ENVIRONMENT VARIABLES

The following environment variables shall affect the execution of od:

LANG
Provide a default value for the internationalization variables that are unset or null. (See the Base Definitions volume of IEEE Std 1003.1-2001, Section 8.2, Internationalization Variables for the precedence of internationalization variables used to determine the values of locale categories.)
LC_ALL
If set to a non-empty string value, override the values of all the other internationalization variables.
LC_CTYPE
Determine the locale for the interpretation of sequences of bytes of text data as characters (for example, single-byte as opposed to multi-byte characters in arguments and input files).
LC_MESSAGES
Determine the locale that should be used to affect the format and contents of diagnostic messages written to standard error.
LC_NUMERIC
Determine the locale for selecting the radix character used when writing floating-point formatted output.
NLSPATH
[XSI] [Option Start] Determine the location of message catalogs for the processing of LC_MESSAGES . [Option End]

ASYNCHRONOUS EVENTS

Default.

STDOUT

See the EXTENDED DESCRIPTION section.

STDERR

The standard error shall be used only for diagnostic messages.

OUTPUT FILES

None.

EXTENDED DESCRIPTION

The od utility shall copy sequentially each input file to standard output, transforming the input data according to the output types specified by the -t option [XSI] [Option Start]  or the -bcdosx options. [Option End] If no output type is specified, the default output shall be as if -t oS had been specified.

The number of bytes transformed by the output type specifier c may be variable depending on the LC_CTYPE category.

The default number of bytes transformed by output type specifiers d, f, o, u, and x corresponds to the various C-language types as follows. If the c99 compiler is present on the system, these specifiers shall correspond to the sizes used by default in that compiler. Otherwise, these sizes may vary among systems that conform to IEEE Std 1003.1-2001.

The type specifier character a specifies that bytes shall be interpreted as named characters from the International Reference Version (IRV) of the ISO/IEC 646:1991 standard. Only the least significant seven bits of each byte shall be used for this type specification. Bytes with the values listed in the following table shall be written using the corresponding names for those characters.

Table: Named Characters in od

Value

Name

Value

Name

Value

Name

Value

Name

\000

nul

\001

soh

\002

stx

\003

etx

\004

eot

\005

enq

\006

ack

\007

bel

\010

bs

\011

ht

\012

lf or nl*

\013

vt

\014

ff

\015

cr

\016

so

\017

si

\020

dle

\021

dc1

\022

dc2

\023

dc3

\024

dc4

\025

nak

\026

syn

\027

etb

\030

can

\031

em

\032

sub

\033

esc

\034

fs

\035

gs

\036

rs

\037

us

\040

sp

\177

del

 

 

 

 

Note:
The "\012" value may be written either as lf or nl.

The type specifier character c specifies that bytes shall be interpreted as characters specified by the current setting of the LC_CTYPE locale category. Characters listed in the table in the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 5, File Format Notation ( '\\', '\a', '\b', '\f', '\n', '\r', '\t', '\v' ) shall be written as the corresponding escape sequences, except that backslash shall be written as a single backslash and a NUL shall be written as '\0'. Other non-printable characters shall be written as one three-digit octal number for each byte in the character. Printable multi-byte characters shall be written in the area corresponding to the first byte of the character; the two-character sequence "**" shall be written in the area corresponding to each remaining byte in the character, as an indication that the character is continued. When either the -j skip or -N count option is specified along with the c type specifier, and this results in an attempt to start or finish in the middle of a multi-byte character, the result is implementation-defined.

The input data shall be manipulated in blocks, where a block is defined as a multiple of the least common multiple of the number of bytes transformed by the specified output types. If the least common multiple is greater than 16, the results are unspecified. Each input block shall be written as transformed by each output type, one per written line, in the order that the output types were specified. If the input block size is larger than the number of bytes transformed by the output type, the output type shall sequentially transform the parts of the input block, and the output from each of the transformations shall be separated by one or more <blank>s.

If, as a result of the specification of the -N option or end-of-file being reached on the last input file, input data only partially satisfies an output type, the input shall be extended sufficiently with null bytes to write the last byte of the input.

Unless -A n is specified, the first output line produced for each input block shall be preceded by the input offset, cumulative across input files, of the next byte to be written. The format of the input offset is unspecified; however, it shall not contain any <blank>s, shall start at the first character of the output line, and shall be followed by one or more <blank>s. In addition, the offset of the byte following the last byte written shall be written after all the input data has been processed, but shall not be followed by any <blank>s.

If no -A option is specified, the input offset base is unspecified.

EXIT STATUS

The following exit values shall be returned:

 0
All input files were processed successfully.
>0
An error occurred.

CONSEQUENCES OF ERRORS

Default.


The following sections are informative.

APPLICATION USAGE

XSI-conformant applications are warned not to use filenames starting with '+' or a first operand starting with a numeric character so that the old functionality can be maintained by implementations, unless they specify one of the -A, -j, or -N options. To guarantee that one of these filenames is always interpreted as a filename, an application could always specify the address base format with the -A option.

EXAMPLES

If a file containing 128 bytes with decimal values zero to 127, in increasing order, is supplied as standard input to the command:

od -A d -t a

on an implementation using an input block size of 16 bytes, the standard output, independent of the current locale setting, would be similar to:

0000000 nul soh stx etx eot enq ack bel  bs  ht  nl  vt  ff  cr  so  si
0000016 dle dc1 dc2 dc3 dc4 nak syn etb can  em sub esc  fs  gs  rs  us
0000032  sp   !   "   #   $   %   &   '   (   )   *   +   ,   -   .  /
0000048   0   1   2   3   4   5   6   7   8   9   :   ;   <   =   >   ?
0000064   @   A   B   C   D   E   F   G   H   I   J   K   L   M   N   O
0000080   P   Q   R   S   T   U   V   W   X   Y   Z   [   \   ]   ^   _
0000096   `   a   b   c   d   e   f   g   h   i   j   k   l   m   n   o
0000112   p   q   r   s   t   u   v   w   x   y   z   {   |   }   ˜ del
0000128

Note that this volume of IEEE Std 1003.1-2001 allows nl or lf to be used as the name for the ISO/IEC 646:1991 standard IRV character with decimal value 10. The IRV names this character lf (line feed), but traditional implementations have referred to this character as newline ( nl) and the POSIX locale character set symbolic name for the corresponding character is a <newline>.

The command:

od -A o -t o2x2x -N 18

on a system with 32-bit words and an implementation using an input block size of 16 bytes could write 18 bytes in approximately the following format:

0000000 032056 031440 041123 042040 052516 044530 020043 031464
          342e   3320   4253   4420   554e   4958   2023   3334
             342e3320      42534420      554e4958      20233334
0000020 032472
          353a
             353a0000
0000022

The command:

od -A d -t f -t o4 -t x4 -N 24 -j 0x15

on a system with 64-bit doubles (for example, IEEE Std 754-1985 double precision floating-point format) would skip 21 bytes of input data and then write 24 bytes in approximately the following format:

0000000    1.00000000000000e+00    1.57350000000000e+01
        07774000000 00000000000 10013674121 35341217270
           3ff00000    00000000    402f3851    eb851eb8
0000016    1.40668230000000e+02
        10030312542 04370303230
           40619562    23e18698
0000024

RATIONALE

The od utility went through several names in early proposals, including hd, xd, and most recently hexdump. There were several objections to all of these based on the following reasons:

The original reasons for not standardizing historical od were also fairly widespread. Those reasons are given below along with rationale explaining why the standard developers believe that this version does not suffer from the indicated problem:

The use of "**" as an indication of continuation of a multi-byte character in c specifier output was chosen based on seeing an implementation that uses this method. The continuation bytes have to be marked in a way that is not ambiguous with another single-byte or multi-byte character.

An early proposal used -S and -n, respectively, for the -j and -N options eventually selected. These were changed to avoid conflicts with historical implementations.

The original standard specified -t o2 as the default when no output type was given. This was changed to -t oS (the length of a short) to accommodate a supercomputer implementation that historically used 64 bits as its default (and that defined shorts as 64 bits). This change should not affect conforming applications. The requirement to support lengths of 1, 2, and 4 was added at the same time to address an historical implementation that had no two-byte data types in its C compiler.

The use of a basic integer data type is intended to allow the implementation to choose a word size commonly used by applications on that architecture.

Previous versions of this standard allowed for implementations with bytes other than eight bits, but this has been modified in this version.

FUTURE DIRECTIONS

All option and operand interfaces marked as extensions may be withdrawn in a future version.

SEE ALSO

c99, sed

CHANGE HISTORY

First released in Issue 2.

Issue 5

In the description of the -c option, the phrase "This is equivalent to -t c." is deleted.

The FUTURE DIRECTIONS section is modified.

Issue 6

The od utility is changed to remove the assumption that short was a two-byte entity, as per the revisions in the IEEE P1003.2b draft standard.

The normative text is reworded to avoid use of the term "must" for application requirements.

IEEE Std 1003.1-2001/Cor 1-2002, item XCU/TC1/D6/33 is applied, correcting the examples which used an undefined -n option, which should have been -N.

IEEE Std 1003.1-2001/Cor 2-2004, item XCU/TC2/D6/19 is applied, removing text describing behavior on systems with bytes consisting of more than eight bits.

End of informative text.

UNIX ® is a registered Trademark of The Open Group.
POSIX ® is a registered Trademark of The IEEE.
[ Main Index | XBD | XCU | XSH | XRAT ]