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 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
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 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 -jskip is specified)
are not available, it shall not be considered an error; the od
utility shall format the input that is available.
-o
Interpret words (two-byte units) in octal. This shall be equivalent
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, 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
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.
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; the last
operand shall be interpreted as an offset operand on
XSI-conformant 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 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.
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
Determine the location of message catalogs for the processing of LC_MESSAGES
.
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 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 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.
*
For the type specifier characters d , o , u , and
x , the default number of bytes shall
correspond to the size of the underlying implementation’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-language 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
corresponding 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 implementation’s basic double precision floating-point
data type. The implementation 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
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 ( ’\#146;
,
’\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 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 -jskip or
-Ncount 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.
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.
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:
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:
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 simple 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 intersection
of features provided by both does not meet the
needs of the user community. In fact, the System V version only provides
a mechanism 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 version 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 historical 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 version. 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, double, 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
implementation 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
utility 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 provided. 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-tuL.
*
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 sedl commands. The c
type specifier does this without difficulty and is
completely compatible with the historical implementations 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
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.
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
OD (P)
2003
Generated by OpenAsthra.com from man1p/od.1p using man macros with tbl support.
