path: root/coreutils-5.3.0-bin/man/cat1p/od.1p.txt

od(P)                                                     od(P)





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 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 signifi-
       cant.

       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  equiva-
              lent 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 num-
              bers.

       -d     Interpret words (two-byte units) in unsigned dec-
              imal. 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 inter-
       preted 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 inter-
       preted  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 hexa-
       decimal 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  deci-
              mal. 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 indi-
              cating 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 mul-
              tiple -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 aster-
              isk ( '*' ).

       -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 spec-
       ified.

OPERANDS
       The following operands shall be supported:

       file   A pathname of a file to be read. If no file oper-
              ands  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 oper-
       and  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 op-
       erand on XSI-conformant  systems.   Under  these  condi-
       tions,  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 dec-
              imal. If 'b' is appended,  the  offset  shall  be
              interpreted in units of 512 bytes.


STDIN
       The  standard  input shall be used only if no file oper-
       ands are specified. 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 internationaliza-
              tion 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  cate-
              gories.)

       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 mes-
              sages written to standard error.

       LC_NUMERIC

              Determine the  locale  for  selecting  the  radix
              character  used  when writing floating-point for-
              matted 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 accord-
       ing 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  speci-
       fied.

       The number of bytes transformed by the output type spec-
       ifier c may be variable depending on the LC_CTYPE  cate-
       gory.

       The  default  number of bytes transformed by output type
       specifiers d , f , o , u , and x corresponds to the var-
       ious 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. Other-
       wise, 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  charac-
              ters,  the implementation shall support values of
              the optional number of bytes to be converted cor-
              responding  to  the number of bytes in the C-lan-
              guage types char, short,  int,  and  long.  These
              numbers  can  also be specified by an application
              as the characters 'C' , 'S' , 'I'  ,  and  'L'  ,
              respectively.  The implementation shall also sup-
              port the values 1, 2, 4, and 8, even if  it  pro-
              vides  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 cor-
              respond 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 corre-
              sponding to the number of bytes in the C-language
              types  float, double, and long double. These num-
              bers can also be specified by an  application  as
              the  characters  'F'  ,  'D'  , and 'L' , respec-
              tively.

       The type specifier  character  a  specifies  that  bytes
       shall be interpreted as named characters from the Inter-
       national 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  charac-
       ters.
       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 cur-
       rent setting of the LC_CTYPE locale category. Characters
       listed  in  the  table in the Base Definitions volume of
       IEEE Std 1003.1-2001, Chapter 5, File Format Notation  (
       '\\'  , '\a' , '\b' , '\f' , '\n' , '\r' , '\t' , '\v' )
       shall be written as the corresponding escape  sequences,
       except that backslash shall be written as a single back-
       slash 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  implementa-
       tion-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 -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 mul-
       tiple of the number of bytes transformed by  the  speci-
       fied  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 out-
       put 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  out-
       put  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 off-
       set, cumulative across input files, of the next byte  to
       be  written.  The format of the input offset is unspeci-
       fied; 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  pro-
       cessed, but shall not be followed by any <blank>s.

       If  no  -A option is specified, the input offset base is
       unspecified.

EXIT STATUS
       The following exit values shall be returned:

        0     All input files were processed successfully.

       >0     An error occurred.


CONSEQUENCES OF ERRORS
       Default.

       The following sections are informative.

APPLICATION USAGE
       XSI-conformant applications are warned not to use  file-
       names 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 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 new-
       line ( 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  for-
       mat) 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  pro-
       posals,  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 histori-
              cal implementations and there was no need to cre-
              ate  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 pro-
              vided 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, hexa-
              decimal 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 pre-
              sented here provides more  normalized  forms  for
              dumping  bytes, shorts, ints, and longs in octal,
              signed decimal, unsigned decimal,  and  hexadeci-
              mal;  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  devel-
              opers.  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 corre-
              sponding  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 charac-
              ters 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 lan-
              guage 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 com-
              piler (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, corre-
              sponding 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  con-
              stants  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 vol-
              ume  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 -t uL.

              The  method  of  specifying  the  format  for the
              address field based on specifying a starting off-
              set   in   a  file  unnecessarily  tied  the  two
              together. The -A option now specifies the address
              base  and the -S option specifies a starting off-
              set.

              It would be difficult to break the dependence  on
              U.S.  ASCII to achieve an internationalized util-
              ity. 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  speci-
              fier  does  this  without  difficulty and is com-
              pletely compatible with the historical  implemen-
              tations  of  the c format character when the cur-
              rent   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 deci-
              phered 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 implementa-
       tions.

       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.

FUTURE DIRECTIONS
       All option and operand interfaces marked  as  extensions
       may be withdrawn in a future version.

SEE ALSO
       c99 , sed

COPYRIGHT
       Portions  of  this  text are reprinted and reproduced in
       electronic form from  IEEE  Std  1003.1,  2003  Edition,
       Standard  for Information Technology -- Portable Operat-
       ing System Interface (POSIX), The Open Group Base Speci-
       fications  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.open-
       group.org/unix/online.html .



POSIX                         2003                        od(P)