| blob | 96396f3b79f4290c9c4a62baa9bd215c635add1d |
1 .\" $NetBSD: hexdump.1,v 1.24 2012/07/06 14:10:06 wiz 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 June 24, 2012
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 .Op Fl e Ar format_string
42 .Op Fl f Ar format_file
43 .Op Fl n Ar length
44 .Op Fl s Ar skip
45 .Op Ar
46 .Sh DESCRIPTION
47 The
48 .Nm
49 utility is a filter which displays each specified
50 .Ar file ,
51 or the standard input if no
52 .Ar file
53 arguments are specified, in a user specified
54 format.
55 .Pp
56 The options are as follows:
57 .Bl -tag -width Fl
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.
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
68 .Sq |
69 characters.
70 .It Fl c
71 .Em One-byte character display .
72 Display the input offset in hexadecimal, followed by sixteen
73 space-separated, three column, space-filled, characters of input
74 data per line.
75 .It Fl d
76 .Em Two-byte decimal display .
77 Display the input offset in hexadecimal, followed by eight
78 space-separated, five column, zero-filled, two-byte units
79 of input data, in unsigned decimal, per line.
80 .It Fl e Ar format_string
81 Specify a format string to be used for displaying data.
82 .It Fl f Ar format_file
83 Specify a file that contains one or more newline separated format strings.
84 Empty lines and lines whose first non-blank character is a hash mark
85 .Pq Sq #
86 are ignored.
87 .It Fl n Ar length
88 Interpret only
89 .Ar length
90 bytes of input.
91 .It Fl o
92 .Em Two-byte octal display .
93 Display the input offset in hexadecimal, followed by eight
94 space-separated, six column, zero-filled, two byte quantities of
95 input data, in octal, per line.
96 .It Fl s Ar skip
97 Skip
98 .Ar skip
99 bytes from the beginning of the input.
100 By default,
101 .Ar skip
102 is interpreted as a decimal number.
103 With a leading
104 .Cm 0x
105 or
106 .Cm 0X ,
107 .Ar skip
108 is interpreted as a hexadecimal number;
109 otherwise, with a leading
110 .Cm 0 ,
111 .Ar skip
112 is interpreted as an octal number.
113 Appending the character
114 .Cm b ,
115 .Cm k ,
116 or
117 .Cm m
118 to
119 .Ar skip
120 causes it to be interpreted as a multiple of
121 .Li 512 ,
122 .Li 1024 ,
123 or
124 .Li 1048576 ,
125 respectively.
126 .It Fl v
127 The
128 .Fl v
129 option causes
130 .Nm
131 to display all input data.
132 Without the
133 .Fl v
134 option, any number of groups of output lines, which would be
135 identical to the immediately preceding group of output lines (except
136 for the input offsets), are replaced with a line containing a
137 single asterisk
138 .Pq Sq \&* .
139 .It Fl x
140 .Em Two-byte hexadecimal display .
141 Display the input offset in hexadecimal, followed by eight, space
142 separated, four column, zero-filled, two-byte quantities of input
143 data, in hexadecimal, per line.
144 .El
145 .Pp
146 For each input file,
147 .Nm
148 sequentially copies the input to standard output, transforming the
149 data according to the format strings specified by the
150 .Fl e
151 and
152 .Fl f
153 options, in the order that they were specified.
154 .Ss Formats
155 A format string contains any number of format units, separated by
156 whitespace.
157 A format unit contains up to three items: an iteration count, a byte
158 count, and a format.
159 .Pp
160 The iteration count is an optional positive integer, which defaults to
161 one.
162 Each format is applied iteration count times.
163 .Pp
164 The byte count is an optional positive integer.
165 If specified it defines the number of bytes to be interpreted by
166 each iteration of the format.
167 .Pp
168 If an iteration count and/or a byte count is specified, a single slash
169 .Pq Sq /
170 must be placed after the iteration count and/or before the byte count
171 to disambiguate them.
172 Any whitespace before or after the slash is ignored.
173 .Pp
174 The format is required and must be surrounded by double quote
175 .Pq Sq \&"
176 marks.
177 It is interpreted as a fprintf-style format string (see
178 .Xr fprintf 3 ) ,
179 with the
180 following exceptions:
181 .Bl -bullet -offset indent
182 .It
183 An asterisk
184 .Pq Sq \&*
185 may not be used as a field width or precision.
186 .It
187 A byte count or field precision
188 .Em is
189 required for each
190 .Sq s
191 conversion
192 character (unlike the
193 .Xr fprintf 3
194 default which prints the entire string if the precision is unspecified).
195 .It
196 The conversion characters
197 .Sq h ,
198 .Sq l ,
199 .Sq n ,
200 .Sq p ,
201 and
202 .Sq q
203 are
204 not supported.
205 .It
206 The single character escape sequences
207 described in the C standard are supported:
208 .Bd -ragged -offset indent -compact
209 .Bl -column Xalert_characterX
210 .It NUL \e0
211 .It Aq alert character \ea
212 .It Aq backspace \eb
213 .It Aq form-feed \ef
214 .It Aq newline \en
215 .It Aq carriage return \er
216 .It Aq tab \et
217 .It Aq vertical tab \ev
218 .El
219 .Ed
220 .El
221 .Pp
222 .Nm
223 also supports the following additional conversion strings:
224 .Bl -tag -width Fl
225 .It Cm \&_a Ns Op Cm dox
226 Display the input offset, cumulative across input files, of the
227 next byte to be displayed.
228 The appended characters
229 .Cm d ,
230 .Cm o ,
231 and
232 .Cm x
233 specify the display base
234 as decimal, octal or hexadecimal respectively.
235 .It Cm \&_A Ns Op Cm dox
236 Identical to the
237 .Cm \&_a
238 conversion string except that it is only performed
239 once, when all of the input data has been processed.
240 .It Cm \&_c
241 Output characters in the default character set.
242 Non-printing characters are displayed in three character, zero-padded
243 octal, except for those representable by standard escape notation
244 (see above),
245 which are displayed as two character strings.
246 .It Cm _p
247 Output characters in the default character set.
248 Non-printing characters are displayed as a single
249 .Sq Cm \&. .
250 .It Cm _u
251 Output US ASCII characters, with the exception that control characters are
252 displayed using the following, lower-case, names.
253 Characters greater than 0xff, hexadecimal, are displayed as hexadecimal
254 strings.
255 .Bl -column \&000_nu \&001_so \&002_st \&003_et \&004_eo
256 .It \&000\ nul Ta 001\ soh Ta 002\ stx Ta 003\ etx Ta 004\ eot Ta 005\ enq
257 .It \&006\ ack Ta 007\ bel Ta 008\ bs Ta 009\ ht Ta 00A\ lf Ta 00B\ vt
258 .It \&00C\ ff Ta 00D\ cr Ta 00E\ so Ta 00F\ si Ta 010\ dle Ta 011\ dc1
259 .It \&012\ dc2 Ta 013\ dc3 Ta 014\ dc4 Ta 015\ nak Ta 016\ syn Ta 017\ etb
260 .It \&018\ can Ta 019\ em Ta 01A\ sub Ta 01B\ esc Ta 01C\ fs Ta 01D\ gs
261 .It \&01E\ rs Ta 01F\ us Ta 07F\ del
262 .El
263 .El
264 .Pp
265 The default and supported byte counts for the conversion characters
266 are as follows:
267 .Bl -tag -width "Xc,_Xc,_Xc,_Xc,_Xc,_Xc" -offset indent
268 .It Li \&%_c , \&%_p , \&%_u , \&%c
269 One byte counts only.
270 .It Li \&%d , \&%i , \&%o , \&%u , \&%X , \&%x
271 Four byte default, one, two, four and eight byte counts supported.
272 .It Li \&%E , \&%e , \&%f , \&%G , \&%g
273 Eight byte default, four byte counts supported.
274 .El
275 .Pp
276 The amount of data interpreted by each format string is the sum of the
277 data required by each format unit, which is the iteration count times the
278 byte count, or the iteration count times the number of bytes required by
279 the format if the byte count is not specified.
280 .Pp
281 The input is manipulated in
282 .Dq blocks ,
283 where a block is defined as the
284 largest amount of data specified by any format string.
285 Format strings interpreting less than an input block's worth of data,
286 whose last format unit both interprets some number of bytes and does
287 not have a specified iteration count, have the iteration count
288 incremented until the entire input block has been processed or there
289 is not enough data remaining in the block to satisfy the format string.
290 .Pp
291 If, either as a result of user specification or
292 .Nm
293 modifying
294 the iteration count as described above, an iteration count is
295 greater than one, no trailing whitespace characters are output
296 during the last iteration.
297 .Pp
298 It is an error to specify a byte count as well as multiple conversion
299 characters or strings unless all but one of the conversion characters
300 or strings is
301 .Cm \&_a
302 or
303 .Cm \&_A .
304 .Pp
305 If, as a result of the specification of the
306 .Fl n
307 option or end-of-file being reached, input data only partially
308 satisfies a format string, the input block is zero-padded sufficiently
309 to display all available data (i.e. any format units overlapping the
310 end of data will display some number of the zero bytes).
311 .Pp
312 Further output by such format strings is replaced by an equivalent
313 number of spaces.
314 An equivalent number of spaces is defined as the number of spaces
315 output by an
316 .Cm s
317 conversion character with the same field width
318 and precision as the original conversion character or conversion
319 string but with any
320 .Sq Li \&+ ,
321 .Sq \&\ \& ,
322 and
323 .Sq Li \&#
324 conversion flag characters
325 removed, and referencing a
326 .Dv NULL
327 string.
328 .Pp
329 If no format strings are specified, the default display is equivalent
330 to specifying the
331 .Fl x
332 option.
333 .Sh EXIT STATUS
334 .Ex -std
335 .Sh EXAMPLES
336 Display the input in perusal format:
337 .Bd -literal -offset indent
338 "%06.6_ao " 12/1 "%3_u "
339 "\et\et" "%_p "
340 "\en"
341 .Ed
342 .Pp
343 Implement the
344 .Fl x
345 option:
346 .Bd -literal -offset indent
347 "%07.7_Ax\en"
348 "%07.7_ax " 8/2 "%04x " "\en"
349 .Ed
350 .Sh SEE ALSO
351 .Xr od 1