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