Annotation of src/usr.bin/hexdump/hexdump.1, Revision 1.23
1.23 ! otto 1: .\" $OpenBSD: hexdump.1,v 1.22 2011/05/04 06:49:11 jmc Exp $
1.13 pvalchev 2: .\" $NetBSD: hexdump.1,v 1.14 2001/12/07 14:46:24 bjh21 Exp $
3: .\"
4: .\" Copyright (c) 1989, 1990, 1993
5: .\" The Regents of the University of California. All rights reserved.
1.1 deraadt 6: .\"
7: .\" Redistribution and use in source and binary forms, with or without
8: .\" modification, are permitted provided that the following conditions
9: .\" are met:
10: .\" 1. Redistributions of source code must retain the above copyright
11: .\" notice, this list of conditions and the following disclaimer.
12: .\" 2. Redistributions in binary form must reproduce the above copyright
13: .\" notice, this list of conditions and the following disclaimer in the
14: .\" documentation and/or other materials provided with the distribution.
1.14 millert 15: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 16: .\" may be used to endorse or promote products derived from this software
17: .\" without specific prior written permission.
18: .\"
19: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
20: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
21: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
22: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
23: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
24: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
25: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
26: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
27: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
28: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
29: .\" SUCH DAMAGE.
30: .\"
1.13 pvalchev 31: .\" from: @(#)hexdump.1 8.2 (Berkeley) 4/18/94
1.1 deraadt 32: .\"
1.23 ! otto 33: .Dd $Mdocdate: May 4 2011 $
1.1 deraadt 34: .Dt HEXDUMP 1
35: .Os
36: .Sh NAME
37: .Nm hexdump
38: .Nd ascii, decimal, hexadecimal, octal dump
39: .Sh SYNOPSIS
40: .Nm hexdump
1.13 pvalchev 41: .Bk -words
1.18 jmc 42: .Op Fl bCcdovx
1.1 deraadt 43: .Op Fl e Ar format_string
44: .Op Fl f Ar format_file
45: .Op Fl n Ar length
1.18 jmc 46: .Op Fl s Ar offset
47: .Op Ar
1.13 pvalchev 48: .Ek
1.1 deraadt 49: .Sh DESCRIPTION
1.5 aaron 50: The
1.8 aaron 51: .Nm
1.5 aaron 52: utility is a filter which displays the specified files, or
53: the standard input, if no files are specified, in a user-specified
1.1 deraadt 54: format.
55: .Pp
56: The options are as follows:
1.12 aaron 57: .Bl -tag -width Ds
1.1 deraadt 58: .It Fl b
59: .Em One-byte octal display .
60: Display the input offset in hexadecimal, followed by sixteen
61: space-separated, three column, zero-filled, bytes of input data,
62: in octal, per line.
1.18 jmc 63: .It Fl C
64: .Em Canonical hex+ASCII display .
65: Display the input offset in hexadecimal, followed by sixteen
66: space-separated, two column, hexadecimal bytes, followed by the
67: same sixteen bytes in %_p format enclosed in ``|'' characters.
1.1 deraadt 68: .It Fl c
69: .Em One-byte character display .
70: Display the input offset in hexadecimal, followed by sixteen
71: space-separated, three column, space-filled, characters of input
72: data per line.
73: .It Fl d
1.5 aaron 74: .Em Two-byte decimal display .
1.1 deraadt 75: Display the input offset in hexadecimal, followed by eight
76: space-separated, five column, zero-filled, two-byte units
77: of input data, in unsigned decimal, per line.
1.7 aaron 78: .It Fl e Ar format_string
1.1 deraadt 79: Specify a format string to be used for displaying data.
1.7 aaron 80: .It Fl f Ar format_file
1.1 deraadt 81: Specify a file that contains one or more newline separated format strings.
82: Empty lines and lines whose first non-blank character is a hash mark
1.10 aaron 83: .Pq Ql #
1.1 deraadt 84: are ignored.
1.7 aaron 85: .It Fl n Ar length
1.1 deraadt 86: Interpret only
87: .Ar length
88: bytes of input.
1.15 miod 89: By default,
90: .Ar length
91: is interpreted as a decimal number.
92: With a leading
93: .Cm 0x
94: or
95: .Cm 0X ,
96: .Ar length
97: is interpreted as a hexadecimal number,
98: otherwise, with a leading
99: .Cm 0 ,
100: .Ar length
101: is interpreted as an octal number.
1.1 deraadt 102: .It Fl o
1.6 aaron 103: .Em Two-byte octal display .
1.1 deraadt 104: Display the input offset in hexadecimal, followed by eight
105: space-separated, six column, zero-filled, two byte quantities of
106: input data, in octal, per line.
1.7 aaron 107: .It Fl s Ar offset
1.1 deraadt 108: Skip
109: .Ar offset
110: bytes from the beginning of the input.
111: By default,
112: .Ar offset
113: is interpreted as a decimal number.
114: With a leading
115: .Cm 0x
116: or
117: .Cm 0X ,
118: .Ar offset
119: is interpreted as a hexadecimal number,
120: otherwise, with a leading
121: .Cm 0 ,
122: .Ar offset
123: is interpreted as an octal number.
124: Appending the character
125: .Cm b ,
126: .Cm k ,
127: or
128: .Cm m
129: to
130: .Ar offset
131: causes it to be interpreted as a multiple of
132: .Li 512 ,
133: .Li 1024 ,
134: or
135: .Li 1048576 ,
136: respectively.
137: .It Fl v
138: The
139: .Fl v
140: option causes hexdump to display all input data.
141: Without the
142: .Fl v
143: option, any number of groups of output lines, which would be
144: identical to the immediately preceding group of output lines (except
145: for the input offsets), are replaced with a line comprised of a
1.10 aaron 146: single asterisk
147: .Pq Ql * .
1.1 deraadt 148: .It Fl x
1.6 aaron 149: .Em Two-byte hexadecimal display .
1.1 deraadt 150: Display the input offset in hexadecimal, followed by eight, space
151: separated, four column, zero-filled, two-byte quantities of input
152: data, in hexadecimal, per line.
153: .El
154: .Pp
155: For each input file,
1.8 aaron 156: .Nm
1.1 deraadt 157: sequentially copies the input to standard output, transforming the
158: data according to the format strings specified by the
159: .Fl e
160: and
161: .Fl f
162: options, in the order that they were specified.
163: .Ss Formats
164: A format string contains any number of format units, separated by
165: whitespace.
166: A format unit contains up to three items: an iteration count, a byte
167: count, and a format.
168: .Pp
169: The iteration count is an optional positive integer, which defaults to
170: one.
171: Each format is applied iteration count times.
172: .Pp
173: The byte count is an optional positive integer.
174: If specified it defines the number of bytes to be interpreted by
175: each iteration of the format.
176: .Pp
177: If an iteration count and/or a byte count is specified, a single slash
1.10 aaron 178: .Pq Sq /
1.1 deraadt 179: must be placed after the iteration count and/or before the byte count
180: to disambiguate them.
181: Any whitespace before or after the slash is ignored.
182: .Pp
183: The format is required and must be surrounded by double quote
1.10 aaron 184: .Pq \&"\& \&"
1.22 jmc 185: marks
186: (the quote mark is a special character in many shell programs,
187: and may have to be escaped from the shell).
1.13 pvalchev 188: It is interpreted as a fprintf-style format string (see
1.1 deraadt 189: .Xr fprintf 3 ) ,
190: with the
191: following exceptions:
192: .Bl -bullet -offset indent
193: .It
194: An asterisk (*) may not be used as a field width or precision.
195: .It
196: A byte count or field precision
197: .Em is
1.10 aaron 198: required for each
199: .Sq s
200: conversion character (unlike the
1.1 deraadt 201: .Xr fprintf 3
202: default which prints the entire string if the precision is unspecified).
203: .It
1.10 aaron 204: The conversion characters
205: .Sq h ,
1.13 pvalchev 206: .Sq l ,
1.10 aaron 207: .Sq n ,
1.13 pvalchev 208: .Sq p ,
1.10 aaron 209: and
1.13 pvalchev 210: .Sq q
1.10 aaron 211: are not supported.
1.1 deraadt 212: .It
213: The single character escape sequences
214: described in the C standard are supported:
1.16 jmc 215: .Pp
1.17 jmc 216: .Bl -tag -width "Xalert characterXXX" -offset indent -compact
1.16 jmc 217: .It NUL
218: \e0
219: .It Aq alert character
220: \ea
221: .It Aq backspace
222: \eb
223: .It Aq form-feed
224: \ef
225: .It Aq newline
226: \en
227: .It Aq carriage return
228: \er
229: .It Aq tab
230: \et
231: .It Aq vertical tab
232: \ev
1.1 deraadt 233: .El
234: .El
235: .Pp
1.8 aaron 236: .Nm
1.5 aaron 237: also supports the following additional conversion strings:
1.1 deraadt 238: .Bl -tag -width Fl
1.7 aaron 239: .It Cm \&_a Ns Op Cm dox
1.1 deraadt 240: Display the input offset, cumulative across input files, of the
241: next byte to be displayed.
242: The appended characters
243: .Cm d ,
244: .Cm o ,
245: and
246: .Cm x
247: specify the display base
248: as decimal, octal or hexadecimal respectively.
1.7 aaron 249: .It Cm \&_A Ns Op Cm dox
1.1 deraadt 250: Identical to the
251: .Cm \&_a
252: conversion string except that it is only performed
253: once, when all of the input data has been processed.
254: .It Cm \&_c
255: Output characters in the default character set.
256: Nonprinting characters are displayed in three character, zero-padded
257: octal, except for those representable by standard escape notation
258: (see above),
259: which are displayed as two character strings.
260: .It Cm _p
261: Output characters in the default character set.
1.10 aaron 262: Nonprinting characters are displayed as a single dot
263: .Ql \&. .
1.1 deraadt 264: .It Cm _u
265: Output US ASCII characters, with the exception that control characters are
266: displayed using the following, lower-case, names.
267: Characters greater than 0xff, hexadecimal, are displayed as hexadecimal
268: strings.
269: .Bl -column \&000_nu \&001_so \&002_st \&003_et \&004_eo
270: .It \&000\ nul\t001\ soh\t002\ stx\t003\ etx\t004\ eot\t005\ enq
271: .It \&006\ ack\t007\ bel\t008\ bs\t009\ ht\t00A\ lf\t00B\ vt
272: .It \&00C\ ff\t00D\ cr\t00E\ so\t00F\ si\t010\ dle\t011\ dc1
273: .It \&012\ dc2\t013\ dc3\t014\ dc4\t015\ nak\t016\ syn\t017\ etb
274: .It \&018\ can\t019\ em\t01A\ sub\t01B\ esc\t01C\ fs\t01D\ gs
1.20 naddy 275: .It \&01E\ rs\t01F\ us\t07F\ del
1.1 deraadt 276: .El
277: .El
278: .Pp
279: The default and supported byte counts for the conversion characters
280: are as follows:
281: .Bl -tag -width "Xc,_Xc,_Xc,_Xc,_Xc,_Xc" -offset indent
282: .It Li \&%_c , \&%_p , \&%_u , \&%c
283: One byte counts only.
284: .It Xo
285: .Li \&%d , \&%i , \&%o ,
1.7 aaron 286: .Li \&%u , \&%X , \&%x
1.1 deraadt 287: .Xc
1.13 pvalchev 288: Four byte default, one, two, four and eight byte counts supported.
1.1 deraadt 289: .It Xo
290: .Li \&%E , \&%e , \&%f ,
1.7 aaron 291: .Li \&%G , \&%g
1.1 deraadt 292: .Xc
293: Eight byte default, four byte counts supported.
294: .El
295: .Pp
296: The amount of data interpreted by each format string is the sum of the
297: data required by each format unit, which is the iteration count times the
298: byte count, or the iteration count times the number of bytes required by
299: the format if the byte count is not specified.
300: .Pp
1.10 aaron 301: The input is manipulated in
302: .Dq blocks ,
303: where a block is defined as the
1.1 deraadt 304: largest amount of data specified by any format string.
305: Format strings interpreting less than an input block's worth of data,
306: whose last format unit both interprets some number of bytes and does
1.3 deraadt 307: not have a specified iteration count, have the iteration count
1.1 deraadt 308: incremented until the entire input block has been processed or there
309: is not enough data remaining in the block to satisfy the format string.
310: .Pp
311: If, either as a result of user specification or hexdump modifying
312: the iteration count as described above, an iteration count is
313: greater than one, no trailing whitespace characters are output
314: during the last iteration.
315: .Pp
316: It is an error to specify a byte count as well as multiple conversion
317: characters or strings unless all but one of the conversion characters
318: or strings is
319: .Cm \&_a
320: or
321: .Cm \&_A .
322: .Pp
323: If, as a result of the specification of the
324: .Fl n
325: option or end-of-file being reached, input data only partially
326: satisfies a format string, the input block is zero-padded sufficiently
1.11 aaron 327: to display all available data (i.e., any format units overlapping the
1.1 deraadt 328: end of data will display some number of the zero bytes).
329: .Pp
330: Further output by such format strings is replaced by an equivalent
331: number of spaces.
332: An equivalent number of spaces is defined as the number of spaces
333: output by an
334: .Cm s
335: conversion character with the same field width
336: and precision as the original conversion character or conversion
337: string but with any
1.10 aaron 338: .Ql + ,
339: .Ql \&\ \& ,
340: .Ql #
1.1 deraadt 341: conversion flag characters
342: removed, and referencing a NULL string.
343: .Pp
344: If no format strings are specified, the default display is equivalent
345: to specifying the
346: .Fl x
347: option.
1.21 jmc 348: .Sh EXIT STATUS
1.17 jmc 349: .Ex -std hexdump
1.1 deraadt 350: .Sh EXAMPLES
1.22 jmc 351: Display characters using a fieldwidth of 4,
352: and using special names for control characters:
353: .Pp
354: .Dl $ hexdump -e '"%4_u"' file
355: .Pp
356: An example file for use with the
357: .Fl f
358: option, to display the input in perusal format:
1.1 deraadt 359: .Bd -literal -offset indent
360: "%06.6_ao " 12/1 "%3_u "
361: "\et\et" "%_p "
362: "\en"
363: .Ed
364: .Pp
1.22 jmc 365: An example file for use with the
366: .Fl f
367: option, which implements the equivalent of the
368: .Fl x
369: option:
1.1 deraadt 370: .Bd -literal -offset indent
371: "%07.7_Ax\en"
1.23 ! otto 372: "%07.7_ax " 8/2 " %04x " "\en"
1.1 deraadt 373: .Ed
1.10 aaron 374: .Sh SEE ALSO
375: .Xr od 1