OD(1P) POSIX Programmer's Manual OD(1P)PROLOG
This manual page is part of the POSIX Programmer's Manual. The Linux
implementation of this interface may differ (consult the corresponding
Linux manual page for details of Linux behavior), or the interface may
not be implemented on Linux.
NAMEod - dump files in various formats
SYNOPSISod [-v][-A address_base][-j skip][-N count][-t type_string]...
[file...]
od [-bcdosx][file] [[+]offset[.][b]]
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 and the -bcdosx
options is significant.
The following options shall be supported:
-A address_base
Specify the input offset base. See the EXTENDED DESCRIPTION sec‐
tion. 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 Interpret bytes in octal. This shall be equivalent to -t o1.
-c 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.
-d Interpret words (two-byte units) in unsigned decimal. This shall
be equivalent to -t u2.
-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 con‐
catenated 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 hexadeci‐
mal, 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; other‐
wise, 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 consid‐
ered an error; the od utility shall format the input that is
available.
-o Interpret words (two-byte units) in octal. This shall be equiva‐
lent to -t o2.
-s Interpret words (two-byte units) in signed decimal. This shall
be equivalent to -t d2.
-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, respec‐
tively. 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 immedi‐
ately preceding group of output lines (except for the byte off‐
sets), shall be replaced with a line containing only an asterisk
( '*' ).
-x Interpret words (two-byte units) in hexadecimal. This shall be
equivalent to -t x2.
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.
OPERANDS
The following operands shall be supported:
file A pathname of a file to be read. If no file operands are speci‐
fied, 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; the
last operand shall be interpreted as an offset operand on XSI-confor‐
mant systems. Under these conditions, the results are unspecified on
systems that are not XSI-conformant systems.
[+]offset[.][b]
The offset operand specifies the offset in the file where dump‐
ing 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.
STDIN
The standard input shall be used only if no file operands are speci‐
fied. 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 Vari‐
ables 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
Determine the location of message catalogs for the processing of
LC_MESSAGES .
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 out‐
put, transforming the input data according to the output types speci‐
fied by the -t option or the -bcdosx options. 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 cor‐
respond to the sizes used by default in that compiler. Otherwise, these
sizes may vary among systems that conform to IEEE Std 1003.1-2001.
* For the type specifier characters d, o, u, and x, the default number
of bytes shall correspond to the size of the underlying implementa‐
tion's basic integer type. For these specifier characters, the
implementation shall support values of the optional number of bytes
to be converted corresponding to the number of bytes in the C-lan‐
guage types char, short, int, and long. These numbers can also be
specified by an application as the characters 'C', 'S', 'I', and
'L', respectively. The implementation shall also support the values
1, 2, 4, and 8, even if it provides no C-Language types of those
sizes. The implementation shall support the decimal value corre‐
sponding to the C-language type long long. The byte order used when
interpreting numeric values is implementation-defined, but shall
correspond to the order in which a constant of the corresponding
type is stored in memory on the system.
* For the type specifier character f, the default number of bytes
shall correspond to the number of bytes in the underlying implemen‐
tation's basic double precision floating-point data type. The imple‐
mentation shall support values of the optional number of bytes to be
converted corresponding to the number of bytes in the C-language
types float, double, and long double. These numbers can also be
specified by an application as the characters 'F', 'D', and 'L',
respectively.
The type specifier character a specifies that bytes shall be inter‐
preted 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 inter‐
preted 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. If the size of a byte on the system is
greater than nine bits, the format used for non-printable characters is
implementation-defined. Printable multi-byte characters shall be writ‐
ten 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 satis‐
fies 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 stan‐
dard output, independent of the current locale setting, would be simi‐
lar 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 tra‐
ditional implementations have referred to this character as newline (
nl) and the POSIX locale character set symbolic name for the corre‐
sponding 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 fol‐
lowing 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 hd and xd names conflicted with historical utilities that
behaved differently.
* The hexdump description was much more complex than needed for a sim‐
ple dump utility.
* The od utility has been available on all historical implementations
and there was no need to create a new name for a utility so similar
to the historical od utility.
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 BSD and System V versions of od have diverged, and the intersec‐
tion of features provided by both does not meet the needs of the
user community. In fact, the System V version only provides a mecha‐
nism for dumping octal bytes and shorts, signed and unsigned decimal
shorts, hexadecimal shorts, and ASCII characters. BSD added the
ability to dump floats, doubles, named ASCII characters, and octal,
signed decimal, unsigned decimal, and hexadecimal longs. The ver‐
sion presented here provides more normalized forms for dumping
bytes, shorts, ints, and longs in octal, signed decimal, unsigned
decimal, and hexadecimal; float, double, and long double; and named
ASCII as well as current locale characters.
* It would not be possible to come up with a compatible superset of
the BSD and System V flags that met the requirements of the standard
developers. The historical default od output is the specified
default output of this utility. None of the option letters chosen
for this version of od conflict with any of the options to histori‐
cal versions of od.
* On systems with different sizes for short, int, and long, there was
no way to ask for dumps of ints, even in the BSD version. Because of
the way options are named, the name space could not be extended to
solve these problems. This is why the -t option was added (with type
specifiers more closely matched to the printf() formats used in the
rest of this volume of IEEE Std 1003.1-2001) and the optional field
sizes were added to the d, f, o, u, and x type specifiers. It is
also one of the reasons why the historical practice was not mandated
as a required obsolescent form of od. (Although the old versions of
od are not listed as an obsolescent form, implementations are urged
to continue to recognize the older forms for several more years.)
The a, c, f, o, and x types match the meaning of the corresponding
format characters in the historical implementations of od except for
the default sizes of the fields converted. The d format is signed in
this volume of IEEE Std 1003.1-2001 to match the printf() notation.
(Historical versions of od used d as a synonym for u in this ver‐
sion. The System V implementation uses s for signed decimal; BSD
uses i for signed decimal and s for null-terminated strings.) Other
than d and u, all of the type specifiers match format characters in
the historical BSD version of od.
The sizes of the C-language types char, short, int, long, float, dou‐
ble, and long double are used even though it is recognized that there
may be zero or more than one compiler for the C language on an imple‐
mentation and that they may use different sizes for some of these
types. (For example, one compiler might use 2 bytes shorts, 2 bytes
ints, and 4 bytes longs, while another compiler (or an option to the
same compiler) uses 2 bytes shorts, 4 bytes ints, and 4 bytes longs.)
Nonetheless, there has to be a basic size known by the implementation
for these types, corresponding to the values reported by invocations of
the getconf utility when called with system_var operands {UCHAR_MAX},
{USHORT_MAX}, {UINT_MAX}, and {ULONG_MAX} for the types char, short,
int, and long, respectively. There are similar constants required by
the ISO C standard, but not required by the System Interfaces volume of
IEEE Std 1003.1-2001 or this volume of IEEE Std 1003.1-2001. They are
{FLT_MANT_DIG}, {DBL_MANT_DIG}, and {LDBL_MANT_DIG} for the types
float, double, and long double, respectively. If the optional c99 util‐
ity is provided by the implementation and used as specified by this
volume of IEEE Std 1003.1-2001, these are the sizes that would be pro‐
vided. If an option is used that specifies different sizes for these
types, there is no guarantee that the od utility is able to interpret
binary data output by such a program correctly.
This volume of IEEE Std 1003.1-2001 requires that the numeric values of
these lengths be recognized by the od utility and that symbolic forms
also be recognized. Thus, a conforming application can always look at
an array of unsigned long data elements using od-t uL.
* The method of specifying the format for the address field based on
specifying a starting offset in a file unnecessarily tied the two
together. The -A option now specifies the address base and the -S
option specifies a starting offset.
* It would be difficult to break the dependence on U.S. ASCII to
achieve an internationalized utility. It does not seem to be any
harder for od to dump characters in the current locale than it is
for the ed or sed l commands. The c type specifier does this without
difficulty and is completely compatible with the historical imple‐
mentations of the c format character when the current locale uses a
superset of the ISO/IEC 646:1991 standard as a codeset. The a type
specifier (from the BSD a format character) was left as a portable
means to dump ASCII (or more correctly ISO/IEC 646:1991 standard
(IRV)) so that headers produced by pax could be deciphered even on
systems that do not use the ISO/IEC 646:1991 standard as a subset of
their base codeset.
The use of "**" as an indication of continuation of a multi-byte char‐
acter in c specifier output was chosen based on seeing an implementa‐
tion 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 histor‐
ical 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 implemen‐
tation to choose a word size commonly used by applications on that
architecture.
FUTURE DIRECTIONS
All option and operand interfaces marked as extensions may be withdrawn
in a future version.
SEE ALSO
c99, sed
COPYRIGHT
Portions of this text are reprinted and reproduced in electronic form
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
-- Portable Operating System Interface (POSIX), The Open Group Base
Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
Electrical and Electronics Engineers, Inc and The Open Group. In the
event of any discrepancy between this version and the original IEEE and
The Open Group Standard, the original IEEE and The Open Group Standard
is the referee document. The original Standard can be obtained online
at http://www.opengroup.org/unix/online.html .
IEEE/The Open Group 2003 OD(1P)
