od.html

IEEE 1003.1-2003, Single Unix Specification v3

<tt>c</tt> 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.</p>

<p>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 &lt;blank&gt;s.</p>

<p>If, as a result of the specification of the <b>-N</b> 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.</p>

<p>Unless <b>-A&nbsp;n</b> 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 &lt;blank&gt;s, shall start at the first character of the output line, and shall be followed by one or more
&lt;blank&gt;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 &lt;blank&gt;s.</p>

<p>If no <b>-A</b> option is specified, the input offset base is unspecified.</p>
</blockquote>

<h4><a name="tag_04_96_14"></a>EXIT STATUS</h4>

<blockquote>
<p>The following exit values shall be returned:</p>

<dl compact>
<dt>&nbsp;0</dt>

<dd>All input files were processed successfully.</dd>

<dt>&gt;0</dt>

<dd>An error occurred.</dd>
</dl>
</blockquote>

<h4><a name="tag_04_96_15"></a>CONSEQUENCES OF ERRORS</h4>

<blockquote>
<p>Default.</p>
</blockquote>

<hr>
<div class="box"><em>The following sections are informative.</em></div>

<h4><a name="tag_04_96_16"></a>APPLICATION USAGE</h4>

<blockquote>
<p>XSI-conformant applications are warned not to use filenames starting with <tt>'+'</tt> 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 <b>-A</b>,
<b>-j</b>, or <b>-N</b> 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 <b>-A</b> option.</p>
</blockquote>

<h4><a name="tag_04_96_17"></a>EXAMPLES</h4>

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

<pre>
<tt>od -A d -t a
</tt>
</pre>

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

<pre>
<tt>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   !   "   #   $   %   &amp;   '   (   )   *   +   ,   -   .  /
0000048   0   1   2   3   4   5   6   7   8   9   :   ;   &lt;   =   &gt;   ?
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   {   |   }   &#152; del
0000128
</tt>
</pre>

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

<p>The command:</p>

<pre>
<tt>od -A o -t o2x2x -N 18
</tt>
</pre>

<p>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:</p>

<pre>
<tt>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
</tt>
</pre>

<p>The command:</p>

<pre>
<tt>od -A d -t f -t o4 -t x4 -N 24 -j 0x15
</tt>
</pre>

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

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

<h4><a name="tag_04_96_18"></a>RATIONALE</h4>

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

<ul>
<li>
<p>The <i>hd</i> and <i>xd</i> names conflicted with historical utilities that behaved differently.</p>
</li>

<li>
<p>The <i>hexdump</i> description was much more complex than needed for a simple dump utility.</p>
</li>

<li>
<p>The <i>od</i> 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 <i>od</i> utility.</p>
</li>
</ul>

<p>The original reasons for not standardizing historical <i>od</i> 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:</p>

<ul>
<li>
<p>The BSD and System V versions of <i>od</i> 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 <b>short</b>s,
signed and unsigned decimal <b>short</b>s, hexadecimal <b>short</b>s, and ASCII characters. BSD added the ability to dump
<b>float</b>s, <b>double</b>s, named ASCII characters, and octal, signed decimal, unsigned decimal, and hexadecimal <b>long</b>s.
The version presented here provides more normalized forms for dumping bytes, <b>short</b>s, <b>int</b>s, and <b>long</b>s in octal,
signed decimal, unsigned decimal, and hexadecimal; <b>float</b>, <b>double</b>, and <b>long double</b>; and named ASCII as well as
current locale characters.</p>
</li>

<li>
<p>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 <i>od</i> output is the specified default output of this utility. None of the option
letters chosen for this version of <i>od</i> conflict with any of the options to historical versions of <i>od</i>.</p>
</li>

<li>
<p>On systems with different sizes for <b>short</b>, <b>int</b>, and <b>long</b>, there was no way to ask for dumps of <b>int</b>s,
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 <b>-t</b> option was added (with type specifiers more closely matched to the <a href=
"../functions/printf.html"><i>printf</i>()</a> formats used in the rest of this volume of IEEE&nbsp;Std&nbsp;1003.1-2001) and the
optional field sizes were added to the <tt>d</tt> , <tt>f</tt> , <tt>o</tt> , <tt>u</tt> , and <tt>x</tt> type specifiers. It is
also one of the reasons why the historical practice was not mandated as a required obsolescent form of <i>od</i>. (Although the old
versions of <i>od</i> are not listed as an obsolescent form, implementations are urged to continue to recognize the older forms for
several more years.) The <tt>a</tt> , <tt>c</tt> , <tt>f</tt> , <tt>o</tt> , and <tt>x</tt> types match the meaning of the
corresponding format characters in the historical implementations of <i>od</i> except for the default sizes of the fields
converted. The <tt>d</tt> format is signed in this volume of IEEE&nbsp;Std&nbsp;1003.1-2001 to match the <a href=
"../functions/printf.html"><i>printf</i>()</a> notation. (Historical versions of <i>od</i> used <tt>d</tt> as a synonym for
<tt>u</tt> in this version. The System V implementation uses <tt>s</tt> for signed decimal; BSD uses <tt>i</tt> for signed decimal
and <tt>s</tt> for null-terminated strings.) Other than <tt>d</tt> and <tt>u</tt> , all of the type specifiers match format
characters in the historical BSD version of <b>od</b>.</p>

<p>The sizes of the C-language types <b>char</b>, <b>short</b>, <b>int</b>, <b>long</b>, <b>float</b>, <b>double</b>, and <b>long
double</b> 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
<b>short</b>s, 2 bytes <b>int</b>s, and 4 bytes <b>long</b>s, while another compiler (or an option to the same compiler) uses 2
bytes <b>short</b>s, 4 bytes <b>int</b>s, and 4 bytes <b>long</b>s.) Nonetheless, there has to be a basic size known by the
implementation for these types, corresponding to the values reported by invocations of the <a href=
"../utilities/getconf.html"><i>getconf</i></a> utility when called with <i>system_var</i> operands {UCHAR_MAX}, {USHORT_MAX},
{UINT_MAX}, and {ULONG_MAX} for the types <b>char</b>, <b>short</b>, <b>int</b>, and <b>long</b>, respectively. There are similar
constants required by the ISO&nbsp;C standard, but not required by the System Interfaces volume of IEEE&nbsp;Std&nbsp;1003.1-2001
or this volume of IEEE&nbsp;Std&nbsp;1003.1-2001. They are {FLT_MANT_DIG}, {DBL_MANT_DIG}, and {LDBL_MANT_DIG} for the types
<b>float</b>, <b>double</b>, and <b>long double</b>, respectively. If the optional <a href="../utilities/c99.html"><i>c99</i></a>
utility is provided by the implementation and used as specified by this volume of IEEE&nbsp;Std&nbsp;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
<i>od</i> utility is able to interpret binary data output by such a program correctly.</p>

<p>This volume of IEEE&nbsp;Std&nbsp;1003.1-2001 requires that the numeric values of these lengths be recognized by the <i>od</i>
utility and that symbolic forms also be recognized. Thus, a conforming application can always look at an array of <b>unsigned
long</b> data elements using <i>od</i> <b>-t</b> <i>uL</i>.</p>
</li>

<li>
<p>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 <b>-A</b> option now specifies the address base and the <b>-S</b> option specifies a starting offset.</p>
</li>

<li>
<p>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 <i>od</i> to dump characters in the current locale than it is for the <a href="../utilities/ed.html"><i>ed</i></a> or <a
href="../utilities/sed.html"><i>sed</i></a> <b>l</b> commands. The <tt>c</tt> type specifier does this without difficulty and is
completely compatible with the historical implementations of the <b>c</b> format character when the current locale uses a superset
of the ISO/IEC&nbsp;646:1991 standard as a codeset. The <tt>a</tt> type specifier (from the BSD <b>a</b> format character) was left
as a portable means to dump ASCII (or more correctly ISO/IEC&nbsp;646:1991 standard (IRV)) so that headers produced by <a href=
"../utilities/pax.html"><i>pax</i></a> could be deciphered even on systems that do not use the ISO/IEC&nbsp;646:1991 standard as a
subset of their base codeset.</p>
</li>
</ul>

<p>The use of <tt>"**"</tt> as an indication of continuation of a multi-byte character in <tt>c</tt> 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.</p>

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

<p>The original standard specified <b>-t o2</b> as the default when no output type was given. This was changed to <b>-t oS</b> (the
length of a <b>short</b>) 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.</p>

<p>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.</p>
</blockquote>

<h4><a name="tag_04_96_19"></a>FUTURE DIRECTIONS</h4>

<blockquote>
<p>All option and operand interfaces marked as extensions may be withdrawn in a future version.</p>
</blockquote>

<h4><a name="tag_04_96_20"></a>SEE ALSO</h4>

<blockquote>
<p><a href="c99.html"><i>c99</i></a> , <a href="sed.html"><i>sed</i></a></p>
</blockquote>

<h4><a name="tag_04_96_21"></a>CHANGE HISTORY</h4>

<blockquote>
<p>First released in Issue 2.</p>
</blockquote>

<h4><a name="tag_04_96_22"></a>Issue 5</h4>

<blockquote>
<p>In the description of the <b>-c</b> option, the phrase &quot;This is equivalent to <b>-t&nbsp;c</b>.&quot; is deleted.</p>

<p>The FUTURE DIRECTIONS section is modified.</p>
</blockquote>

<h4><a name="tag_04_96_23"></a>Issue 6</h4>

<blockquote>
<p>The <i>od</i> utility is changed to remove the assumption that <b>short</b> was a two-byte entity, as per the revisions in the
IEEE&nbsp;P1003.2b draft standard.</p>

<p>The normative text is reworded to avoid use of the term &quot;must&quot; for application requirements.</p>

<p>IEEE&nbsp;Std 1003.1-2001/Cor&nbsp;1-2002, item XCU/TC1/D6/33 is applied, correcting the examples which used an undefined
<b>-n</b> option, which should have been <b>-N</b>.</p>
</blockquote>

<div class="box"><em>End of informative text.</em></div>

<hr>
<hr size="2" noshade>
<center><font size="2"><!--footer start-->
UNIX &reg; is a registered Trademark of The Open Group.<br>
POSIX &reg; is a registered Trademark of The IEEE.<br>
[ <a href="../mindex.html">Main Index</a> | <a href="../basedefs/contents.html">XBD</a> | <a href=
"../utilities/contents.html">XCU</a> | <a href="../functions/contents.html">XSH</a> | <a href="../xrat/contents.html">XRAT</a>
]</font></center>

<!--footer end-->
<hr size="2" noshade>
</body>
</html>