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