1OD(P) POSIX Programmer's Manual OD(P)
2
6 od - dump files in various formats
7
9 od [-v][-A address_base][-j skip][-N count][-t type_string]...
10 [file...]
11 od [-bcdosx][file] [[+]offset[.][b]]
15
18 The od utility shall write the contents of its input files to standard
19 output in a user-specified format.
20
22 The od utility shall conform to the Base Definitions volume of
23 IEEE Std 1003.1-2001, Section 12.2, Utility Syntax Guidelines, except
24 that the order of presentation of the -t options and the -bcdosx
25 options is significant.
26 The following options shall be supported:
28 -A address_base
30 Specify the input offset base. See the EXTENDED DESCRIPTION sec‐
32 tion. The application shall ensure that the address_base
33 option-argument is a character. The characters 'd' , 'o' , and
34 'x' specify that the offset base shall be written in decimal,
35 octal, or hexadecimal, respectively. The character 'n' specifies
36 that the offset shall not be written.
37 -b Interpret bytes in octal. This shall be equivalent to -t o1.
39 -c Interpret bytes as characters specified by the current setting
41 of the LC_CTYPE category. Certain non-graphic characters appear
42 as C escapes: "NUL=\0" , "BS=\b" , "FF=\f" , "NL=\n" , "CR=\r" ,
43 "HT=\t" ; others appear as 3-digit octal numbers.
44 -d Interpret words (two-byte units) in unsigned decimal. This shall
46 be equivalent to -t u2.
47 -j skip
49 Jump over skip bytes from the beginning of the input. The od
50 utility shall read or seek past the first skip bytes in the con‐
51 catenated input files. If the combined input is not at least
52 skip bytes long, the od utility shall write a diagnostic message
53 to standard error and exit with a non-zero exit status.
54 By default, the skip option-argument shall be interpreted as a decimal
56 number. With a leading 0x or 0X, the offset shall be interpreted as a
57 hexadecimal number; otherwise, with a leading '0' , the offset shall be
58 interpreted as an octal number. Appending the character 'b' , 'k' , or
59 'm' to offset shall cause it to be interpreted as a multiple of 512,
60 1024, or 1048576 bytes, respectively. If the skip number is hexadeci‐
61 mal, any appended 'b' shall be considered to be the final hexadecimal
62 digit.
63 -N count
65 Format no more than count bytes of input. By default, count
66 shall be interpreted as a decimal number. With a leading 0x or
67 0X, count shall be interpreted as a hexadecimal number; other‐
68 wise, with a leading '0' , it shall be interpreted as an octal
69 number. If count bytes of input (after successfully skipping, if
70 -j skip is specified) are not available, it shall not be consid‐
71 ered an error; the od utility shall format the input that is
72 available.
73 -o Interpret words (two-byte units) in octal. This shall be equiva‐
75 lent to -t o2.
76 -s Interpret words (two-byte units) in signed decimal. This shall
78 be equivalent to -t d2.
79 -t type_string
81 Specify one or more output types. See the EXTENDED DESCRIPTION
83 section. The application shall ensure that the type_string
84 option-argument is a string specifying the types to be used when
85 writing the input data. The string shall consist of the type
86 specification characters a , c , d , f , o , u , and x , speci‐
87 fying named character, character, signed decimal, floating
88 point, octal, unsigned decimal, and hexadecimal, respectively.
89 The type specification characters d , f , o , u , and x can be
90 followed by an optional unsigned decimal integer that specifies
91 the number of bytes to be transformed by each instance of the
92 output type. The type specification character f can be followed
93 by an optional F , D , or L indicating that the conversion
94 should be applied to an item of type float, double, or long dou‐
95 ble, respectively. The type specification characters d , o , u ,
96 and x can be followed by an optional C , S , I , or L indicating
97 that the conversion should be applied to an item of type char,
98 short, int, or long, respectively. Multiple types can be con‐
99 catenated within the same type_string and multiple -t options
100 can be specified. Output lines shall be written for each type
101 specified in the order in which the type specification charac‐
102 ters are specified.
103 -v Write all input data. Without the -v option, any number of
105 groups of output lines, which would be identical to the immedi‐
106 ately preceding group of output lines (except for the byte off‐
107 sets), shall be replaced with a line containing only an asterisk
108 ( '*' ).
109 -x Interpret words (two-byte units) in hexadecimal. This shall be
111 equivalent to -t x2.
112 Multiple types can be specified by using multiple -bcdostx options.
115 Output lines are written for each type specified in the order in which
116 the types are specified.
117
119 The following operands shall be supported:
120 file A pathname of a file to be read. If no file operands are speci‐
122 fied, the standard input shall be used.
123 If there are no more than two operands, none of the -A, -j, -N, or -t
125 options is specified, and either of the following is true: the first
126 character of the last operand is a plus sign ( '+' ), or there are two
127 operands and the first character of the last operand is numeric; the
128 last operand shall be interpreted as an offset operand on XSI-confor‐
129 mant systems. Under these conditions, the results are unspecified on
130 systems that are not XSI-conformant systems.
131 [+]offset[.][b]
133 The offset operand specifies the offset in the file where dump‐
134 ing is to commence. This operand is normally interpreted as
135 octal bytes. If '.' is appended, the offset shall be interpreted
136 in decimal. If 'b' is appended, the offset shall be interpreted
137 in units of 512 bytes.
138
141 The standard input shall be used only if no file operands are speci‐
142 fied. See the INPUT FILES section.
143
145 The input files can be any file type.
146
148 The following environment variables shall affect the execution of od:
149 LANG Provide a default value for the internationalization variables
151 that are unset or null. (See the Base Definitions volume of
152 IEEE Std 1003.1-2001, Section 8.2, Internationalization Vari‐
153 ables for the precedence of internationalization variables used
154 to determine the values of locale categories.)
155 LC_ALL If set to a non-empty string value, override the values of all
157 the other internationalization variables.
158 LC_CTYPE
160 Determine the locale for the interpretation of sequences of
161 bytes of text data as characters (for example, single-byte as
162 opposed to multi-byte characters in arguments and input files).
163 LC_MESSAGES
165 Determine the locale that should be used to affect the format
166 and contents of diagnostic messages written to standard error.
167 LC_NUMERIC
169 Determine the locale for selecting the radix character used when
171 writing floating-point formatted output.
172 NLSPATH
174 Determine the location of message catalogs for the processing of
175 LC_MESSAGES .
176
179 Default.
180
182 See the EXTENDED DESCRIPTION section.
183
185 The standard error shall be used only for diagnostic messages.
186
188 None.
189
191 The od utility shall copy sequentially each input file to standard out‐
192 put, transforming the input data according to the output types speci‐
193 fied by the -t option or the -bcdosx options. If no output type is
194 specified, the default output shall be as if -t oS had been specified.
195 The number of bytes transformed by the output type specifier c may be
197 variable depending on the LC_CTYPE category.
198 The default number of bytes transformed by output type specifiers d , f
200 , o , u , and x corresponds to the various C-language types as follows.
201 If the c99 compiler is present on the system, these specifiers shall
202 correspond to the sizes used by default in that compiler. Otherwise,
203 these sizes may vary among systems that conform to
204 IEEE Std 1003.1-2001.
205 * For the type specifier characters d , o , u , and x , the default
207 number of bytes shall correspond to the size of the underlying
208 implementation's basic integer type. For these specifier characters,
209 the implementation shall support values of the optional number of
210 bytes to be converted corresponding to the number of bytes in the C-
211 language types char, short, int, and long. These numbers can also be
212 specified by an application as the characters 'C' , 'S' , 'I' , and
213 'L' , respectively. The implementation shall also support the val‐
214 ues 1, 2, 4, and 8, even if it provides no C-Language types of those
215 sizes. The implementation shall support the decimal value corre‐
216 sponding to the C-language type long long. The byte order used when
217 interpreting numeric values is implementation-defined, but shall
218 correspond to the order in which a constant of the corresponding
219 type is stored in memory on the system.
220 * For the type specifier character f , the default number of bytes
222 shall correspond to the number of bytes in the underlying implemen‐
223 tation's basic double precision floating-point data type. The imple‐
224 mentation shall support values of the optional number of bytes to be
225 converted corresponding to the number of bytes in the C-language
226 types float, double, and long double. These numbers can also be
227 specified by an application as the characters 'F' , 'D' , and 'L' ,
228 respectively.
229 The type specifier character a specifies that bytes shall be inter‐
231 preted as named characters from the International Reference Version
232 (IRV) of the ISO/IEC 646:1991 standard. Only the least significant
233 seven bits of each byte shall be used for this type specification.
234 Bytes with the values listed in the following table shall be written
235 using the corresponding names for those characters.
236 Table: Named Characters in od
238 Value Name Value Name Value Name Value Name
240 \000 nul \001 soh \002 stx \003 etx
241 \004 eot \005 enq \006 ack \007 bel
242 \010 bs \011 ht \012 lf or nl \013 vt
243 \014 ff \015 cr \016 so \017 si
244 \020 dle \021 dc1 \022 dc2 \023 dc3
245 \024 dc4 \025 nak \026 syn \027 etb
246 \030 can \031 em \032 sub \033 esc
247 \034 fs \035 gs \036 rs \037 us
248 \040 sp \177 del
249 Note: The "\012" value may be written either as lf or nl.
251 The type specifier character c specifies that bytes shall be inter‐
254 preted as characters specified by the current setting of the LC_CTYPE
255 locale category. Characters listed in the table in the Base Definitions
256 volume of IEEE Std 1003.1-2001, Chapter 5, File Format Notation ( '\\'
257 , '\a' , '\b' , '\f' , '\n' , '\r' , '\t' , '\v' ) shall be written as
258 the corresponding escape sequences, except that backslash shall be
259 written as a single backslash and a NUL shall be written as '\0' .
260 Other non-printable characters shall be written as one three-digit
261 octal number for each byte in the character. If the size of a byte on
262 the system is greater than nine bits, the format used for non-printable
263 characters is implementation-defined. Printable multi-byte characters
264 shall be written in the area corresponding to the first byte of the
265 character; the two-character sequence "**" shall be written in the area
266 corresponding to each remaining byte in the character, as an indication
267 that the character is continued. When either the -j skip or -N count
268 option is specified along with the c type specifier, and this results
269 in an attempt to start or finish in the middle of a multi-byte charac‐
270 ter, the result is implementation-defined.
271 The input data shall be manipulated in blocks, where a block is defined
273 as a multiple of the least common multiple of the number of bytes
274 transformed by the specified output types. If the least common multiple
275 is greater than 16, the results are unspecified. Each input block
276 shall be written as transformed by each output type, one per written
277 line, in the order that the output types were specified. If the input
278 block size is larger than the number of bytes transformed by the output
279 type, the output type shall sequentially transform the parts of the
280 input block, and the output from each of the transformations shall be
281 separated by one or more <blank>s.
282 If, as a result of the specification of the -N option or end-of-file
284 being reached on the last input file, input data only partially satis‐
285 fies an output type, the input shall be extended sufficiently with null
286 bytes to write the last byte of the input.
287 Unless -A n is specified, the first output line produced for each input
289 block shall be preceded by the input offset, cumulative across input
290 files, of the next byte to be written. The format of the input offset
291 is unspecified; however, it shall not contain any <blank>s, shall start
292 at the first character of the output line, and shall be followed by one
293 or more <blank>s. In addition, the offset of the byte following the
294 last byte written shall be written after all the input data has been
295 processed, but shall not be followed by any <blank>s.
296 If no -A option is specified, the input offset base is unspecified.
298
300 The following exit values shall be returned:
301 0 All input files were processed successfully.
303 >0 An error occurred.
305
308 Default.
309 The following sections are informative.
311
313 XSI-conformant applications are warned not to use filenames starting
314 with '+' or a first operand starting with a numeric character so that
315 the old functionality can be maintained by implementations, unless they
316 specify one of the -A, -j, or -N options. To guarantee that one of
317 these filenames is always interpreted as a filename, an application
318 could always specify the address base format with the -A option.
319
321 If a file containing 128 bytes with decimal values zero to 127, in
322 increasing order, is supplied as standard input to the command:
323 od -A d -t a
326 on an implementation using an input block size of 16 bytes, the stan‐
328 dard output, independent of the current locale setting, would be simi‐
329 lar to:
330 0000000 nul soh stx etx eot enq ack bel bs ht nl vt ff cr so si
333 0000016 dle dc1 dc2 dc3 dc4 nak syn etb can em sub esc fs gs rs us
334 0000032 sp ! " # $ % & ' ( ) * + , - . /
335 0000048 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
336 0000064 @ A B C D E F G H I J K L M N O
337 0000080 P Q R S T U V W X Y Z [ \ ] ^ _
338 0000096 ` a b c d e f g h i j k l m n o
339 0000112 p q r s t u v w x y z { | } ~ del
340 0000128
341 Note that this volume of IEEE Std 1003.1-2001 allows nl or lf to be
343 used as the name for the ISO/IEC 646:1991 standard IRV character with
344 decimal value 10. The IRV names this character lf (line feed), but tra‐
345 ditional implementations have referred to this character as newline (
346 nl) and the POSIX locale character set symbolic name for the corre‐
347 sponding character is a <newline>.
348 The command:
350 od -A o -t o2x2x -N 18
353 on a system with 32-bit words and an implementation using an input
355 block size of 16 bytes could write 18 bytes in approximately the fol‐
356 lowing format:
357 0000000 032056 031440 041123 042040 052516 044530 020043 031464
360 342e 3320 4253 4420 554e 4958 2023 3334
361 342e3320 42534420 554e4958 20233334
362 0000020 032472
363 353a
364 353a0000
365 0000022
366 The command:
368 od -A d -t f -t o4 -t x4 -N 24 -j 0x15
371 on a system with 64-bit doubles (for example, IEEE Std 754-1985 double
373 precision floating-point format) would skip 21 bytes of input data and
374 then write 24 bytes in approximately the following format:
375 0000000 1.00000000000000e+00 1.57350000000000e+01
378 07774000000 00000000000 10013674121 35341217270
379 3ff00000 00000000 402f3851 eb851eb8
380 0000016 1.40668230000000e+02
381 10030312542 04370303230
382 40619562 23e18698
383 0000024
384
386 The od utility went through several names in early proposals, including
387 hd, xd, and most recently hexdump. There were several objections to all
388 of these based on the following reasons:
389 * The hd and xd names conflicted with historical utilities that
391 behaved differently.
392 * The hexdump description was much more complex than needed for a sim‐
394 ple dump utility.
395 * The od utility has been available on all historical implementations
397 and there was no need to create a new name for a utility so similar
398 to the historical od utility.
399 The original reasons for not standardizing historical od were also
401 fairly widespread. Those reasons are given below along with rationale
402 explaining why the standard developers believe that this version does
403 not suffer from the indicated problem:
404 * The BSD and System V versions of od have diverged, and the intersec‐
406 tion of features provided by both does not meet the needs of the
407 user community. In fact, the System V version only provides a mecha‐
408 nism for dumping octal bytes and shorts, signed and unsigned decimal
409 shorts, hexadecimal shorts, and ASCII characters. BSD added the
410 ability to dump floats, doubles, named ASCII characters, and octal,
411 signed decimal, unsigned decimal, and hexadecimal longs. The ver‐
412 sion presented here provides more normalized forms for dumping
413 bytes, shorts, ints, and longs in octal, signed decimal, unsigned
414 decimal, and hexadecimal; float, double, and long double; and named
415 ASCII as well as current locale characters.
416 * It would not be possible to come up with a compatible superset of
418 the BSD and System V flags that met the requirements of the standard
419 developers. The historical default od output is the specified
420 default output of this utility. None of the option letters chosen
421 for this version of od conflict with any of the options to histori‐
422 cal versions of od.
423 * On systems with different sizes for short, int, and long, there was
425 no way to ask for dumps of ints, even in the BSD version. Because of
426 the way options are named, the name space could not be extended to
427 solve these problems. This is why the -t option was added (with type
428 specifiers more closely matched to the printf() formats used in the
429 rest of this volume of IEEE Std 1003.1-2001) and the optional field
430 sizes were added to the d , f , o , u , and x type specifiers. It is
431 also one of the reasons why the historical practice was not mandated
432 as a required obsolescent form of od. (Although the old versions of
433 od are not listed as an obsolescent form, implementations are urged
434 to continue to recognize the older forms for several more years.)
435 The a , c , f , o , and x types match the meaning of the correspond‐
436 ing format characters in the historical implementations of od except
437 for the default sizes of the fields converted. The d format is
438 signed in this volume of IEEE Std 1003.1-2001 to match the printf()
439 notation. (Historical versions of od used d as a synonym for u in
440 this version. The System V implementation uses s for signed decimal;
441 BSD uses i for signed decimal and s for null-terminated strings.)
442 Other than d and u , all of the type specifiers match format charac‐
443 ters in the historical BSD version of od.
444 The sizes of the C-language types char, short, int, long, float, dou‐
446 ble, and long double are used even though it is recognized that there
447 may be zero or more than one compiler for the C language on an imple‐
448 mentation and that they may use different sizes for some of these
449 types. (For example, one compiler might use 2 bytes shorts, 2 bytes
450 ints, and 4 bytes longs, while another compiler (or an option to the
451 same compiler) uses 2 bytes shorts, 4 bytes ints, and 4 bytes longs.)
452 Nonetheless, there has to be a basic size known by the implementation
453 for these types, corresponding to the values reported by invocations of
454 the getconf utility when called with system_var operands {UCHAR_MAX},
455 {USHORT_MAX}, {UINT_MAX}, and {ULONG_MAX} for the types char, short,
456 int, and long, respectively. There are similar constants required by
457 the ISO C standard, but not required by the System Interfaces volume of
458 IEEE Std 1003.1-2001 or this volume of IEEE Std 1003.1-2001. They are
459 {FLT_MANT_DIG}, {DBL_MANT_DIG}, and {LDBL_MANT_DIG} for the types
460 float, double, and long double, respectively. If the optional c99 util‐
461 ity is provided by the implementation and used as specified by this
462 volume of IEEE Std 1003.1-2001, these are the sizes that would be pro‐
463 vided. If an option is used that specifies different sizes for these
464 types, there is no guarantee that the od utility is able to interpret
465 binary data output by such a program correctly.
466 This volume of IEEE Std 1003.1-2001 requires that the numeric values of
468 these lengths be recognized by the od utility and that symbolic forms
469 also be recognized. Thus, a conforming application can always look at
470 an array of unsigned long data elements using od -t uL.
471 * The method of specifying the format for the address field based on
473 specifying a starting offset in a file unnecessarily tied the two
474 together. The -A option now specifies the address base and the -S
475 option specifies a starting offset.
476 * It would be difficult to break the dependence on U.S. ASCII to
478 achieve an internationalized utility. It does not seem to be any
479 harder for od to dump characters in the current locale than it is
480 for the ed or sed l commands. The c type specifier does this without
481 difficulty and is completely compatible with the historical imple‐
482 mentations of the c format character when the current locale uses a
483 superset of the ISO/IEC 646:1991 standard as a codeset. The a type
484 specifier (from the BSD a format character) was left as a portable
485 means to dump ASCII (or more correctly ISO/IEC 646:1991 standard
486 (IRV)) so that headers produced by pax could be deciphered even on
487 systems that do not use the ISO/IEC 646:1991 standard as a subset of
488 their base codeset.
489 The use of "**" as an indication of continuation of a multi-byte char‐
491 acter in c specifier output was chosen based on seeing an implementa‐
492 tion that uses this method. The continuation bytes have to be marked in
493 a way that is not ambiguous with another single-byte or multi-byte
494 character.
495 An early proposal used -S and -n, respectively, for the -j and -N
497 options eventually selected. These were changed to avoid conflicts with
498 historical implementations.
499 The original standard specified -t o2 as the default when no output
501 type was given. This was changed to -t oS (the length of a short) to
502 accommodate a supercomputer implementation that historically used 64
503 bits as its default (and that defined shorts as 64 bits). This change
504 should not affect conforming applications. The requirement to support
505 lengths of 1, 2, and 4 was added at the same time to address an histor‐
506 ical implementation that had no two-byte data types in its C compiler.
507 The use of a basic integer data type is intended to allow the implemen‐
509 tation to choose a word size commonly used by applications on that
510 architecture.
511
513 All option and operand interfaces marked as extensions may be withdrawn
514 in a future version.
515
517 c99 , sed
518
520 Portions of this text are reprinted and reproduced in electronic form
521 from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
522 -- Portable Operating System Interface (POSIX), The Open Group Base
523 Specifications Issue 6, Copyright (C) 2001-2003 by the Institute of
524 Electrical and Electronics Engineers, Inc and The Open Group. In the
525 event of any discrepancy between this version and the original IEEE and
526 The Open Group Standard, the original IEEE and The Open Group Standard
527 is the referee document. The original Standard can be obtained online
528 at http://www.opengroup.org/unix/online.html .
529IEEE/The Open Group 2003 OD(P)