mirror of https://github.com/mkerrisk/man-pages
643 lines
26 KiB
Groff
643 lines
26 KiB
Groff
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "OD" P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" od
|
|
.SH NAME
|
|
od \- dump files in various formats
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fBod\fP \fB[\fP\fB-v\fP\fB][\fP\fB-A\fP \fIaddress_base\fP\fB][\fP\fB-j\fP
|
|
\fIskip\fP\fB][\fP\fB-N\fP
|
|
\fIcount\fP\fB][\fP\fB-t\fP \fItype_string\fP\fB]\fP\fB...
|
|
.br
|
|
\ \ \ \ \ \ \fP \fB[\fP\fIfile\fP\fB...\fP\fB]\fP\fB
|
|
.br
|
|
.sp
|
|
\fP
|
|
.LP
|
|
\fBod\fP \fB[\fP\fB-bcdosx\fP\fB][\fP\fIfile\fP\fB]
|
|
[[\fP\fB+\fP\fB]\fP\fIoffset\fP\fB[\fP\fB.\fP\fB][\fP\fBb\fP\fB]]\fP\fB\fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIod\fP utility shall write the contents of its input files to
|
|
standard output in a user-specified format.
|
|
.SH OPTIONS
|
|
.LP
|
|
The \fIod\fP 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
|
|
\fB-t\fP options \ and the \fB-bcdosx\fP options
|
|
is significant.
|
|
.LP
|
|
The following options shall be supported:
|
|
.TP 7
|
|
\fB-A\ \fP \fIaddress_base\fP
|
|
.sp
|
|
Specify the input offset base. See the EXTENDED DESCRIPTION section.
|
|
The application shall ensure that the \fIaddress_base\fP
|
|
option-argument is a character. The characters \fB'd'\fP , \fB'o'\fP
|
|
, and \fB'x'\fP specify that the offset base shall be
|
|
written in decimal, octal, or hexadecimal, respectively. The character
|
|
\fB'n'\fP specifies that the offset shall not be
|
|
written.
|
|
.TP 7
|
|
\fB-b\fP
|
|
Interpret bytes in octal. This shall be equivalent to \fB-t\ o1\fP.
|
|
.TP 7
|
|
\fB-c\fP
|
|
Interpret bytes as characters specified by the current setting of
|
|
the \fILC_CTYPE\fP category. Certain non-graphic characters
|
|
appear as C escapes: \fB"NUL=\\0"\fP , \fB"BS=\\b"\fP , \fB"FF=\\f"\fP
|
|
, \fB"NL=\\n"\fP , \fB"CR=\\r"\fP ,
|
|
\fB"HT=\\t"\fP ; others appear as 3-digit octal numbers.
|
|
.TP 7
|
|
\fB-d\fP
|
|
Interpret \fIword\fPs (two-byte units) in unsigned decimal. This shall
|
|
be equivalent to \fB-t\ u2\fP.
|
|
.TP 7
|
|
\fB-j\ \fP \fIskip\fP
|
|
Jump over \fIskip\fP bytes from the beginning of the input. The \fIod\fP
|
|
utility shall read or seek past the first
|
|
\fIskip\fP bytes in the concatenated input files. If the combined
|
|
input is not at least \fIskip\fP bytes long, the \fIod\fP
|
|
utility shall write a diagnostic message to standard error and exit
|
|
with a non-zero exit status.
|
|
.LP
|
|
By default, the \fIskip\fP 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
|
|
\fB'0'\fP , the offset shall be interpreted as an octal
|
|
number. Appending the character \fB'b'\fP , \fB'k'\fP , or \fB'm'\fP
|
|
to offset shall cause it to be interpreted as a
|
|
multiple of 512, 1024, or 1048576 bytes, respectively. If the \fIskip\fP
|
|
number is hexadecimal, any appended \fB'b'\fP shall be
|
|
considered to be the final hexadecimal digit.
|
|
.TP 7
|
|
\fB-N\ \fP \fIcount\fP
|
|
Format no more than \fIcount\fP bytes of input. By default, \fIcount\fP
|
|
shall be interpreted as a decimal number. With a
|
|
leading 0x or 0X, \fIcount\fP shall be interpreted as a hexadecimal
|
|
number; otherwise, with a leading \fB'0'\fP , it shall be
|
|
interpreted as an octal number. If \fIcount\fP bytes of input (after
|
|
successfully skipping, if \fB-j\fP \fIskip\fP is specified)
|
|
are not available, it shall not be considered an error; the \fIod\fP
|
|
utility shall format the input that is available.
|
|
.TP 7
|
|
\fB-o\fP
|
|
Interpret \fIword\fPs (two-byte units) in octal. This shall be equivalent
|
|
to \fB-t\ o2\fP.
|
|
.TP 7
|
|
\fB-s\fP
|
|
Interpret \fIword\fPs (two-byte units) in signed decimal. This shall
|
|
be equivalent to \fB-t\ d2\fP.
|
|
.TP 7
|
|
\fB-t\ \fP \fItype_string\fP
|
|
.sp
|
|
Specify one or more output types. See the EXTENDED DESCRIPTION section.
|
|
The application shall ensure that the \fItype_string\fP
|
|
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 \fBa\fP , \fBc\fP , \fBd\fP , \fBf\fP , \fBo\fP
|
|
, \fBu\fP , and \fBx\fP , specifying
|
|
named character, character, signed decimal, floating point, octal,
|
|
unsigned decimal, and hexadecimal, respectively. The type
|
|
specification characters \fBd\fP , \fBf\fP , \fBo\fP , \fBu\fP , and
|
|
\fBx\fP 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 \fBf\fP can be followed by an optional \fBF\fP , \fBD\fP
|
|
, or \fBL\fP indicating that the conversion should
|
|
be applied to an item of type \fBfloat\fP, \fBdouble\fP, or \fBlong
|
|
double\fP, respectively. The type specification characters
|
|
\fBd\fP , \fBo\fP , \fBu\fP , and \fBx\fP can be followed by an optional
|
|
\fBC\fP , \fBS\fP , \fBI\fP , or
|
|
\fBL\fP indicating that the conversion should be applied to an item
|
|
of type \fBchar\fP, \fBshort\fP, \fBint\fP, or
|
|
\fBlong\fP, respectively. Multiple types can be concatenated within
|
|
the same \fItype_string\fP and multiple \fB-t\fP options can
|
|
be specified. Output lines shall be written for each type specified
|
|
in the order in which the type specification characters are
|
|
specified.
|
|
.TP 7
|
|
\fB-v\fP
|
|
Write all input data. Without the \fB-v\fP 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 ( \fB'*'\fP ).
|
|
.TP 7
|
|
\fB-x\fP
|
|
Interpret \fIword\fPs (two-byte units) in hexadecimal. This shall
|
|
be equivalent to \fB-t\ x2\fP.
|
|
.sp
|
|
.LP
|
|
Multiple types can be specified by using multiple \fB-bcdostx\fP options.
|
|
Output lines are written for each type specified in the
|
|
order in which the types are specified.
|
|
.SH OPERANDS
|
|
.LP
|
|
The following operands shall be supported:
|
|
.TP 7
|
|
\fIfile\fP
|
|
A pathname of a file to be read. If no \fIfile\fP operands are specified,
|
|
the standard input shall be used.
|
|
.LP
|
|
If there are no more than two operands, none of the \fB-A\fP, \fB-j\fP,
|
|
\fB-N\fP, or \fB-t\fP options is specified, and
|
|
either of the following is true: the first character of the last operand
|
|
is a plus sign ( \fB'+'\fP ), 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.
|
|
.TP 7
|
|
\fB[+]\fP\fIoffset\fP\fB[.][b]\fP
|
|
The \fIoffset\fP operand specifies the offset in the file where dumping
|
|
is to commence. This operand is normally interpreted as
|
|
octal bytes. If \fB'.'\fP is appended, the offset shall be interpreted
|
|
in decimal. If \fB'b'\fP is appended, the offset shall
|
|
be interpreted in units of 512 bytes.
|
|
.sp
|
|
.SH STDIN
|
|
.LP
|
|
The standard input shall be used only if no \fIfile\fP operands are
|
|
specified. See the INPUT FILES section.
|
|
.SH INPUT FILES
|
|
.LP
|
|
The input files can be any file type.
|
|
.SH ENVIRONMENT VARIABLES
|
|
.LP
|
|
The following environment variables shall affect the execution of
|
|
\fIod\fP:
|
|
.TP 7
|
|
\fILANG\fP
|
|
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.)
|
|
.TP 7
|
|
\fILC_ALL\fP
|
|
If set to a non-empty string value, override the values of all the
|
|
other internationalization variables.
|
|
.TP 7
|
|
\fILC_CTYPE\fP
|
|
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).
|
|
.TP 7
|
|
\fILC_MESSAGES\fP
|
|
Determine the locale that should be used to affect the format and
|
|
contents of diagnostic messages written to standard
|
|
error.
|
|
.TP 7
|
|
\fILC_NUMERIC\fP
|
|
.sp
|
|
Determine the locale for selecting the radix character used when writing
|
|
floating-point formatted output.
|
|
.TP 7
|
|
\fINLSPATH\fP
|
|
Determine the location of message catalogs for the processing of \fILC_MESSAGES
|
|
\&.\fP
|
|
.sp
|
|
.SH ASYNCHRONOUS EVENTS
|
|
.LP
|
|
Default.
|
|
.SH STDOUT
|
|
.LP
|
|
See the EXTENDED DESCRIPTION section.
|
|
.SH STDERR
|
|
.LP
|
|
The standard error shall be used only for diagnostic messages.
|
|
.SH OUTPUT FILES
|
|
.LP
|
|
None.
|
|
.SH EXTENDED DESCRIPTION
|
|
.LP
|
|
The \fIod\fP utility shall copy sequentially each input file to standard
|
|
output, transforming the input data according to the
|
|
output types specified by the \fB-t\fP option \ or the \fB-bcdosx\fP
|
|
options. If no output type is specified, the default output shall
|
|
be as if \fB-t\ oS\fP had been
|
|
specified.
|
|
.LP
|
|
The number of bytes transformed by the output type specifier \fBc\fP
|
|
may be variable depending on the \fILC_CTYPE\fP
|
|
category.
|
|
.LP
|
|
The default number of bytes transformed by output type specifiers
|
|
\fBd\fP , \fBf\fP , \fBo\fP , \fBu\fP , and
|
|
\fBx\fP corresponds to the various C-language types as follows. If
|
|
the \fIc99\fP 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.
|
|
.IP " *" 3
|
|
For the type specifier characters \fBd\fP , \fBo\fP , \fBu\fP , and
|
|
\fBx\fP , 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
|
|
\fBchar\fP, \fBshort\fP, \fBint\fP, and \fBlong\fP. These numbers
|
|
can also be specified by an application as the characters
|
|
\fB'C'\fP , \fB'S'\fP , \fB'I'\fP , and \fB'L'\fP , 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 \fBlong long\fP. 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.
|
|
.LP
|
|
.IP " *" 3
|
|
For the type specifier character \fBf\fP , 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 \fBfloat,\fP \fBdouble\fP,
|
|
and \fBlong double\fP. These numbers can also be specified by an application
|
|
as the characters \fB'F'\fP , \fB'D'\fP , and
|
|
\fB'L'\fP , respectively.
|
|
.LP
|
|
.LP
|
|
The type specifier character \fBa\fP 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.
|
|
.br
|
|
.sp
|
|
.ce 1
|
|
\fBTable: Named Characters in \fIod\fP\fP
|
|
.TS C
|
|
center; l2 l2 l2 l2 l2 l2 l2 l.
|
|
\fBValue\fP \fBName\fP \fBValue\fP \fBName\fP \fBValue\fP \fBName\fP \fBValue\fP \fBName\fP
|
|
\\000 \fBnul\fP \\001 \fBsoh\fP \\002 \fBstx\fP \\003 \fBetx\fP
|
|
\\004 \fBeot\fP \\005 \fBenq\fP \\006 \fBack\fP \\007 \fBbel\fP
|
|
\\010 \fBbs\fP \\011 \fBht\fP \\012 \fBlf or nl\fP \\013 \fBvt\fP
|
|
\\014 \fBff\fP \\015 \fBcr\fP \\016 \fBso\fP \\017 \fBsi\fP
|
|
\\020 \fBdle\fP \\021 \fBdc1\fP \\022 \fBdc2\fP \\023 \fBdc3\fP
|
|
\\024 \fBdc4\fP \\025 \fBnak\fP \\026 \fBsyn\fP \\027 \fBetb\fP
|
|
\\030 \fBcan\fP \\031 \fBem\fP \\032 \fBsub\fP \\033 \fBesc\fP
|
|
\\034 \fBfs\fP \\035 \fBgs\fP \\036 \fBrs\fP \\037 \fBus\fP
|
|
\\040 \fBsp\fP \\177 \fBdel\fP \ \fB\ \fP \ \fB\ \fP
|
|
.TE
|
|
.TP 7
|
|
\fBNote:\fP
|
|
The \fB"\\012"\fP value may be written either as \fBlf\fP or \fBnl\fP.
|
|
.sp
|
|
.LP
|
|
The type specifier character \fBc\fP specifies that bytes shall be
|
|
interpreted as characters specified by the current setting
|
|
of the \fILC_CTYPE\fP locale category. Characters listed in the table
|
|
in the Base Definitions volume of
|
|
IEEE\ Std\ 1003.1-2001, Chapter 5, File Format Notation ( \fB'\\\\'\fP
|
|
,
|
|
\fB'\\a'\fP , \fB'\\b'\fP , \fB'\\f'\fP , \fB'\\n'\fP , \fB'\\r'\fP
|
|
, \fB'\\t'\fP , \fB'\\v'\fP ) 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
|
|
\fB'\\0'\fP . 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 \fB"**"\fP 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 \fB-j\fP \fIskip\fP or
|
|
\fB-N\fP \fIcount\fP option is specified along with the
|
|
\fBc\fP 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.
|
|
.LP
|
|
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.
|
|
.LP
|
|
If, as a result of the specification of the \fB-N\fP 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.
|
|
.LP
|
|
Unless \fB-A\ n\fP 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.
|
|
.LP
|
|
If no \fB-A\fP option is specified, the input offset base is unspecified.
|
|
.SH EXIT STATUS
|
|
.LP
|
|
The following exit values shall be returned:
|
|
.TP 7
|
|
\ 0
|
|
All input files were processed successfully.
|
|
.TP 7
|
|
>0
|
|
An error occurred.
|
|
.sp
|
|
.SH CONSEQUENCES OF ERRORS
|
|
.LP
|
|
Default.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
XSI-conformant applications are warned not to use filenames starting
|
|
with \fB'+'\fP 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 \fB-A\fP,
|
|
\fB-j\fP, or \fB-N\fP 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 \fB-A\fP option.
|
|
.SH EXAMPLES
|
|
.LP
|
|
If a file containing 128 bytes with decimal values zero to 127, in
|
|
increasing order, is supplied as standard input to the
|
|
command:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBod -A d -t a
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
on an implementation using an input block size of 16 bytes, the standard
|
|
output, independent of the current locale setting,
|
|
would be similar to:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB0000000 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
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
Note that this volume of IEEE\ Std\ 1003.1-2001 allows \fBnl\fP or
|
|
\fBlf\fP to be used as the name for the
|
|
ISO/IEC\ 646:1991 standard IRV character with decimal value 10. The
|
|
IRV names this character \fBlf\fP (line feed), but
|
|
traditional implementations have referred to this character as newline
|
|
( \fBnl\fP) and the POSIX locale character set symbolic
|
|
name for the corresponding character is a <newline>.
|
|
.LP
|
|
The command:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBod -A o -t o2x2x -N 18
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
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:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB0000000 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
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
The command:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBod -A d -t f -t o4 -t x4 -N 24 -j 0x15
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
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:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fB0000000 1.00000000000000e+00 1.57350000000000e+01
|
|
07774000000 00000000000 10013674121 35341217270
|
|
3ff00000 00000000 402f3851 eb851eb8
|
|
0000016 1.40668230000000e+02
|
|
10030312542 04370303230
|
|
40619562 23e18698
|
|
0000024
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.SH RATIONALE
|
|
.LP
|
|
The \fIod\fP utility went through several names in early proposals,
|
|
including \fIhd\fP, \fIxd\fP, and most recently
|
|
\fIhexdump\fP. There were several objections to all of these based
|
|
on the following reasons:
|
|
.IP " *" 3
|
|
The \fIhd\fP and \fIxd\fP names conflicted with historical utilities
|
|
that behaved differently.
|
|
.LP
|
|
.IP " *" 3
|
|
The \fIhexdump\fP description was much more complex than needed for
|
|
a simple dump utility.
|
|
.LP
|
|
.IP " *" 3
|
|
The \fIod\fP 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 \fIod\fP utility.
|
|
.LP
|
|
.LP
|
|
The original reasons for not standardizing historical \fIod\fP 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:
|
|
.IP " *" 3
|
|
The BSD and System V versions of \fIod\fP 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 \fBshort\fPs,
|
|
signed and unsigned decimal \fBshort\fPs, hexadecimal \fBshort\fPs,
|
|
and ASCII characters. BSD added the ability to dump
|
|
\fBfloat\fPs, \fBdouble\fPs, named ASCII characters, and octal, signed
|
|
decimal, unsigned decimal, and hexadecimal \fBlong\fPs.
|
|
The version presented here provides more normalized forms for dumping
|
|
bytes, \fBshort\fPs, \fBint\fPs, and \fBlong\fPs in octal,
|
|
signed decimal, unsigned decimal, and hexadecimal; \fBfloat\fP, \fBdouble\fP,
|
|
and \fBlong double\fP; and named ASCII as well as
|
|
current locale characters.
|
|
.LP
|
|
.IP " *" 3
|
|
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 \fIod\fP output is the
|
|
specified default output of this utility. None of the option
|
|
letters chosen for this version of \fIod\fP conflict with any of the
|
|
options to historical versions of \fIod\fP.
|
|
.LP
|
|
.IP " *" 3
|
|
On systems with different sizes for \fBshort\fP, \fBint\fP, and \fBlong\fP,
|
|
there was no way to ask for dumps of \fBint\fPs,
|
|
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 \fB-t\fP option was added (with type specifiers more closely
|
|
matched to the \fIprintf\fP() formats used in the rest of this volume
|
|
of IEEE\ Std\ 1003.1-2001) and the
|
|
optional field sizes were added to the \fBd\fP , \fBf\fP , \fBo\fP
|
|
, \fBu\fP , and \fBx\fP type specifiers. It is
|
|
also one of the reasons why the historical practice was not mandated
|
|
as a required obsolescent form of \fIod\fP. (Although the old
|
|
versions of \fIod\fP are not listed as an obsolescent form, implementations
|
|
are urged to continue to recognize the older forms for
|
|
several more years.) The \fBa\fP , \fBc\fP , \fBf\fP , \fBo\fP , and
|
|
\fBx\fP types match the meaning of the
|
|
corresponding format characters in the historical implementations
|
|
of \fIod\fP except for the default sizes of the fields
|
|
converted. The \fBd\fP format is signed in this volume of IEEE\ Std\ 1003.1-2001
|
|
to match the \fIprintf\fP() notation. (Historical versions of \fIod\fP
|
|
used \fBd\fP as a synonym for
|
|
\fBu\fP in this version. The System V implementation uses \fBs\fP
|
|
for signed decimal; BSD uses \fBi\fP for signed decimal
|
|
and \fBs\fP for null-terminated strings.) Other than \fBd\fP and \fBu\fP
|
|
, all of the type specifiers match format
|
|
characters in the historical BSD version of \fBod\fP.
|
|
.LP
|
|
The sizes of the C-language types \fBchar\fP, \fBshort\fP, \fBint\fP,
|
|
\fBlong\fP, \fBfloat\fP, \fBdouble\fP, and \fBlong
|
|
double\fP 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
|
|
\fBshort\fPs, 2 bytes \fBint\fPs, and 4 bytes \fBlong\fPs, while another
|
|
compiler (or an option to the same compiler) uses 2
|
|
bytes \fBshort\fPs, 4 bytes \fBint\fPs, and 4 bytes \fBlong\fPs.)
|
|
Nonetheless, there has to be a basic size known by the
|
|
implementation for these types, corresponding to the values reported
|
|
by invocations of the \fIgetconf\fP utility when called with \fIsystem_var\fP
|
|
operands {UCHAR_MAX}, {USHORT_MAX},
|
|
{UINT_MAX}, and {ULONG_MAX} for the types \fBchar\fP, \fBshort\fP,
|
|
\fBint\fP, and \fBlong\fP, 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
|
|
\fBfloat\fP, \fBdouble\fP, and \fBlong double\fP, respectively. If
|
|
the optional \fIc99\fP
|
|
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
|
|
\fIod\fP utility is able to interpret binary data output by such a
|
|
program correctly.
|
|
.LP
|
|
This volume of IEEE\ Std\ 1003.1-2001 requires that the numeric values
|
|
of these lengths be recognized by the \fIod\fP
|
|
utility and that symbolic forms also be recognized. Thus, a conforming
|
|
application can always look at an array of \fBunsigned
|
|
long\fP data elements using \fIod\fP \fB-t\fP \fIuL\fP.
|
|
.LP
|
|
.IP " *" 3
|
|
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 \fB-A\fP option now specifies the address base and
|
|
the \fB-S\fP option specifies a starting offset.
|
|
.LP
|
|
.IP " *" 3
|
|
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 \fIod\fP to dump characters in the current locale than
|
|
it is for the \fIed\fP or \fIsed\fP \fBl\fP commands. The \fBc\fP
|
|
type specifier does this without difficulty and is
|
|
completely compatible with the historical implementations of the \fBc\fP
|
|
format character when the current locale uses a superset
|
|
of the ISO/IEC\ 646:1991 standard as a codeset. The \fBa\fP type specifier
|
|
(from the BSD \fBa\fP 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 \fIpax\fP could be deciphered
|
|
even on systems that do not use the ISO/IEC\ 646:1991 standard as
|
|
a
|
|
subset of their base codeset.
|
|
.LP
|
|
.LP
|
|
The use of \fB"**"\fP as an indication of continuation of a multi-byte
|
|
character in \fBc\fP 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.
|
|
.LP
|
|
An early proposal used \fB-S\fP and \fB-n\fP, respectively, for the
|
|
\fB-j\fP and \fB-N\fP options eventually selected. These
|
|
were changed to avoid conflicts with historical implementations.
|
|
.LP
|
|
The original standard specified \fB-t o2\fP as the default when no
|
|
output type was given. This was changed to \fB-t oS\fP (the
|
|
length of a \fBshort\fP) 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.
|
|
.LP
|
|
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.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
All option and operand interfaces marked as extensions may be withdrawn
|
|
in a future version.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIc99\fP , \fIsed\fP
|
|
.SH 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 .
|