xenial (1) od.1posix.gz

Provided by: manpages-posix_2013a-1_all bug

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.

NAME

       od — dump files in various formats

SYNOPSIS

       od [−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 POSIX.1‐2008, 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 −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        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.

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, −t, or −v 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.

STDIN

       The  standard  input shall be used if no file operands are specified, and shall be used if a file operand
       is '−' and the implementation treats the '−' as meaning standard input.  Otherwise,  the  standard  input
       shall not be used.  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 POSIX.1‐2008, 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.

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 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 POSIX.1‐2008.

        *  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   NameValue   NameValue     NameValue   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 POSIX.1‐2008, 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> characters.

       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> characters, shall  start  at  the  first
       character  of  the output line, and shall be followed by one or more <blank> characters. 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> characters.

       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 POSIX.1‐2008 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 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  POSIX.1‐2008)  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  POSIX.1‐2008  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  POSIX.1‐2008 or this volume of POSIX.1‐2008. 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 POSIX.1‐2008, 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 POSIX.1‐2008 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 US 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 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.

       Earlier  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 XSI may be removed in a future version.

SEE ALSO

       c99, sed

       The Base Definitions volume of POSIX.1‐2008, Chapter 5, File  Format  Notation,  Chapter  8,  Environment
       Variables, Section 12.2, Utility Syntax Guidelines

       Portions of this text are reprinted and reproduced in electronic form from IEEE Std 1003.1, 2013 Edition,
       Standard for Information Technology -- Portable Operating System Interface (POSIX), The Open  Group  Base
       Specifications  Issue 7, Copyright (C) 2013 by the Institute of Electrical and Electronics Engineers, Inc
       and The Open Group.  (This is POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/online.html .

       Any  typographical  or formatting errors that appear in this page are most likely to have been introduced
       during  the  conversion  of  the  source  files  to  man  page  format.  To  report  such   errors,   see
       https://www.kernel.org/doc/man-pages/reporting_bugs.html .