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