Unix/Linux Go Back    


Linux 2.6 - man page for od (linux section 1posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


OD(P)				    POSIX Programmer's Manual				    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,  Sec-
       tion  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  applica-
	      tion shall ensure that the address_base option-argument is a character. The charac-
	      ters '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 cat-
	      egory.  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 mes-
	      sage 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  charac-
       ter  '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 hexadec-
	      imal  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  speci-
	      fied)  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 appli-
	      cation 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  charac-
	      ter,  character, signed decimal, floating point, octal, unsigned decimal, and hexa-
	      decimal, 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 conver-
	      sion should be applied to an item of type float, double, or  long  double,  respec-
	      tively.  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 con-
	      catenated 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, or -t options is speci-
       fied, 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-confor-
       mant 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  inter-
	      preted in units of 512 bytes.

STDIN
       The  standard  input  shall  be used only if no file operands 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 internationalization variables that  are	unset  or
	      null. (See the Base Definitions volume of IEEE Std 1003.1-2001, Section 8.2, Inter-
	      nationalization 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 interna-
	      tionalization 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 argu-
	      ments and input files).

       LC_MESSAGES
	      Determine the locale that should be used to affect the format and contents of diag-
	      nostic 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  com-
       piler. Otherwise, these sizes may vary among systems that conform to IEEE Std 1003.1-2001.

	* For the type specifier characters d , o , u , and x , the default number of bytes shall
	  correspond to the size of the underlying implementation's basic integer type. For these
	  specifier characters, the implementation shall support values of the optional number of
	  bytes to be converted corresponding to the number of	bytes  in  the	C-language  types
	  char,  short,  int,  and long. These numbers can also be specified by an application as
	  the characters 'C' , 'S' , 'I' , and 'L' , respectively.  The implementation shall also
	  support  the	values	1,  2, 4, and 8, even if it provides no C-Language types of those
	  sizes.  The implementation shall support the decimal value corresponding to the  C-lan-
	  guage type long long. The byte order used when interpreting numeric values is implemen-
	  tation-defined, but shall correspond to the order in which a	constant  of  the  corre-
	  sponding 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  charac-
       ters 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 correspond-
       ing names for those characters.

				     Table: Named Characters in od

			 Value	Name  Value  Name  Value  Name	    Value  Name
			 \000	nul   \001   soh   \002   stx	    \003   etx
			 \004	eot   \005   enq   \006   ack	    \007   bel
			 \010	bs    \011   ht    \012   lf or nl  \013   vt
			 \014	ff    \015   cr    \016   so	    \017   si
			 \020	dle   \021   dc1   \022   dc2	    \023   dc3
			 \024	dc4   \025   nak   \026   syn	    \027   etb
			 \030	can   \031   em    \032   sub	    \033   esc
			 \034	fs    \035   gs    \036   rs	    \037   us
			 \040	sp    \177   del

       Note:  The "\012" value may be written either as lf or nl.

       The type specifier character c specifies that bytes shall  be  interpreted  as  characters
       specified by the current setting of the LC_CTYPE locale category. Characters listed in the
       table in the Base Definitions volume of IEEE Std 1003.1-2001, Chapter 5, File Format Nota-
       tion  (	'\\'  ,  '\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
       implementation-defined.	Printable multi-byte characters shall be written in the area cor-
       responding  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  indica-
       tion that the character is continued. When either the -j skip or -N count option is speci-
       fied 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  trans-
       form  the  parts of the input block, and the output from each of the transformations shall
       be separated by one or more <blank>s.

       If, as a result of the specification of the -N option or end-of-file being reached on  the
       last  input  file,  input data only partially satisfies an output type, the input shall be
       extended sufficiently with null bytes to write the last byte of the input.

       Unless -A n is specified, the first output line produced for each  input  block	shall  be
       preceded  by the input offset, cumulative across input files, of the next byte to be writ-
       ten. The format of the input offset is unspecified; however,  it  shall	not  contain  any
       <blank>s,  shall start at the first character of the output line, and shall be followed by
       one or more <blank>s. In addition, the offset of the byte following the last byte  written
       shall be written after all the input data has been processed, but shall not be followed by
       any <blank>s.

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

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, indepen-
       dent of the current locale setting, would be similar to:

	      0000000 nul soh stx etx eot enq ack bel  bs  ht  nl  vt  ff  cr  so  si
	      0000016 dle dc1 dc2 dc3 dc4 nak syn etb can  em sub esc  fs  gs  rs  us
	      0000032  sp   !	"   #	$   %	&   '	(   )	*   +	,   -	.  /
	      0000048	0   1	2   3	4   5	6   7	8   9	:   ;	<   =	>   ?
	      0000064	@   A	B   C	D   E	F   G	H   I	J   K	L   M	N   O
	      0000080	P   Q	R   S	T   U	V   W	X   Y	Z   [	\   ]	^   _
	      0000096	`   a	b   c	d   e	f   g	h   i	j   k	l   m	n   o
	      0000112	p   q	r   s	t   u	v   w	x   y	z   {	|   }	~ del
	      0000128

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

       The command:

	      od -A o -t o2x2x -N 18

       on a system with 32-bit words and an implementation using an input block size of 16  bytes
       could write 18 bytes in approximately the following format:

	      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 abil-
	  ity to dump floats,  doubles,  named	ASCII  characters,  and  octal,  signed  decimal,
	  unsigned decimal, and hexadecimal longs.  The version presented here provides more nor-
	  malized 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 cho-
	  sen  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 his-
	  torical 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  for-
	  mat  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 char-
	  acters in the historical BSD version of od.

       The  sizes  of the C-language types char, short, int, long, float, double, and long double
       are used even though it is recognized that there may be zero or more than one compiler for
       the  C  language  on  an  implementation and that they may use different sizes for some of
       these types. (For example, one compiler might use 2 bytes shorts,  2  bytes  ints,  and	4
       bytes  longs,  while  another  compiler	(or  an option to the same compiler) uses 2 bytes
       shorts, 4 bytes ints, and 4 bytes longs.)  Nonetheless, there has to be a basic size known
       by the implementation for these types, corresponding to the values reported by invocations
       of the getconf utility when called with	system_var  operands  {UCHAR_MAX},  {USHORT_MAX},
       {UINT_MAX},  and {ULONG_MAX} for the types char, short, int, and long, respectively. There
       are similar constants required by the ISO C standard,  but  not	required  by  the  System
       Interfaces volume of IEEE Std 1003.1-2001 or this volume of IEEE Std 1003.1-2001. They are
       {FLT_MANT_DIG}, {DBL_MANT_DIG}, and {LDBL_MANT_DIG} for the types float, double, and  long
       double,	respectively.  If  the optional c99 utility is provided by the implementation and
       used as specified by this volume of IEEE Std 1003.1-2001, these are the sizes  that  would
       be provided. If an option is used that specifies different sizes for these types, there is
       no guarantee that the od utility is able to interpret binary data output by such a program
       correctly.

       This  volume  of IEEE Std 1003.1-2001 requires that the numeric values of these lengths be
       recognized by the od utility and that symbolic forms also be recognized. Thus, a  conform-
       ing 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 start-
	  ing offset in a file unnecessarily tied the two together. The -A option  now	specifies
	  the address base and the -S option specifies a starting offset.

	* It  would be difficult to break the dependence on U.S. ASCII to achieve an internation-
	  alized utility. It does not seem to be any harder for od to dump characters in the cur-
	  rent	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	continua-
       tion  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.

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

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 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					    OD(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 08:25 PM.