Annotation of src/usr.bin/hexdump/hexdump.1, Revision 1.21
1.21 ! jmc 1: .\" $OpenBSD: hexdump.1,v 1.20 2010/02/25 16:58:56 naddy 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.21 ! jmc 33: .Dd $Mdocdate: February 25 2010 $
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 \&"\& \&"
185: marks.
1.13 pvalchev 186: It is interpreted as a fprintf-style format string (see
1.1 deraadt 187: .Xr fprintf 3 ) ,
188: with the
189: following exceptions:
190: .Bl -bullet -offset indent
191: .It
192: An asterisk (*) may not be used as a field width or precision.
193: .It
194: A byte count or field precision
195: .Em is
1.10 aaron 196: required for each
197: .Sq s
198: conversion character (unlike the
1.1 deraadt 199: .Xr fprintf 3
200: default which prints the entire string if the precision is unspecified).
201: .It
1.10 aaron 202: The conversion characters
203: .Sq h ,
1.13 pvalchev 204: .Sq l ,
1.10 aaron 205: .Sq n ,
1.13 pvalchev 206: .Sq p ,
1.10 aaron 207: and
1.13 pvalchev 208: .Sq q
1.10 aaron 209: are not supported.
1.1 deraadt 210: .It
211: The single character escape sequences
212: described in the C standard are supported:
1.16 jmc 213: .Pp
1.17 jmc 214: .Bl -tag -width "Xalert characterXXX" -offset indent -compact
1.16 jmc 215: .It NUL
216: \e0
217: .It Aq alert character
218: \ea
219: .It Aq backspace
220: \eb
221: .It Aq form-feed
222: \ef
223: .It Aq newline
224: \en
225: .It Aq carriage return
226: \er
227: .It Aq tab
228: \et
229: .It Aq vertical tab
230: \ev
1.1 deraadt 231: .El
232: .El
233: .Pp
1.8 aaron 234: .Nm
1.5 aaron 235: also supports the following additional conversion strings:
1.1 deraadt 236: .Bl -tag -width Fl
1.7 aaron 237: .It Cm \&_a Ns Op Cm dox
1.1 deraadt 238: Display the input offset, cumulative across input files, of the
239: next byte to be displayed.
240: The appended characters
241: .Cm d ,
242: .Cm o ,
243: and
244: .Cm x
245: specify the display base
246: as decimal, octal or hexadecimal respectively.
1.7 aaron 247: .It Cm \&_A Ns Op Cm dox
1.1 deraadt 248: Identical to the
249: .Cm \&_a
250: conversion string except that it is only performed
251: once, when all of the input data has been processed.
252: .It Cm \&_c
253: Output characters in the default character set.
254: Nonprinting characters are displayed in three character, zero-padded
255: octal, except for those representable by standard escape notation
256: (see above),
257: which are displayed as two character strings.
258: .It Cm _p
259: Output characters in the default character set.
1.10 aaron 260: Nonprinting characters are displayed as a single dot
261: .Ql \&. .
1.1 deraadt 262: .It Cm _u
263: Output US ASCII characters, with the exception that control characters are
264: displayed using the following, lower-case, names.
265: Characters greater than 0xff, hexadecimal, are displayed as hexadecimal
266: strings.
267: .Bl -column \&000_nu \&001_so \&002_st \&003_et \&004_eo
268: .It \&000\ nul\t001\ soh\t002\ stx\t003\ etx\t004\ eot\t005\ enq
269: .It \&006\ ack\t007\ bel\t008\ bs\t009\ ht\t00A\ lf\t00B\ vt
270: .It \&00C\ ff\t00D\ cr\t00E\ so\t00F\ si\t010\ dle\t011\ dc1
271: .It \&012\ dc2\t013\ dc3\t014\ dc4\t015\ nak\t016\ syn\t017\ etb
272: .It \&018\ can\t019\ em\t01A\ sub\t01B\ esc\t01C\ fs\t01D\ gs
1.20 naddy 273: .It \&01E\ rs\t01F\ us\t07F\ del
1.1 deraadt 274: .El
275: .El
276: .Pp
277: The default and supported byte counts for the conversion characters
278: are as follows:
279: .Bl -tag -width "Xc,_Xc,_Xc,_Xc,_Xc,_Xc" -offset indent
280: .It Li \&%_c , \&%_p , \&%_u , \&%c
281: One byte counts only.
282: .It Xo
283: .Li \&%d , \&%i , \&%o ,
1.7 aaron 284: .Li \&%u , \&%X , \&%x
1.1 deraadt 285: .Xc
1.13 pvalchev 286: Four byte default, one, two, four and eight byte counts supported.
1.1 deraadt 287: .It Xo
288: .Li \&%E , \&%e , \&%f ,
1.7 aaron 289: .Li \&%G , \&%g
1.1 deraadt 290: .Xc
291: Eight byte default, four byte counts supported.
292: .El
293: .Pp
294: The amount of data interpreted by each format string is the sum of the
295: data required by each format unit, which is the iteration count times the
296: byte count, or the iteration count times the number of bytes required by
297: the format if the byte count is not specified.
298: .Pp
1.10 aaron 299: The input is manipulated in
300: .Dq blocks ,
301: where a block is defined as the
1.1 deraadt 302: largest amount of data specified by any format string.
303: Format strings interpreting less than an input block's worth of data,
304: whose last format unit both interprets some number of bytes and does
1.3 deraadt 305: not have a specified iteration count, have the iteration count
1.1 deraadt 306: incremented until the entire input block has been processed or there
307: is not enough data remaining in the block to satisfy the format string.
308: .Pp
309: If, either as a result of user specification or hexdump modifying
310: the iteration count as described above, an iteration count is
311: greater than one, no trailing whitespace characters are output
312: during the last iteration.
313: .Pp
314: It is an error to specify a byte count as well as multiple conversion
315: characters or strings unless all but one of the conversion characters
316: or strings is
317: .Cm \&_a
318: or
319: .Cm \&_A .
320: .Pp
321: If, as a result of the specification of the
322: .Fl n
323: option or end-of-file being reached, input data only partially
324: satisfies a format string, the input block is zero-padded sufficiently
1.11 aaron 325: to display all available data (i.e., any format units overlapping the
1.1 deraadt 326: end of data will display some number of the zero bytes).
327: .Pp
328: Further output by such format strings is replaced by an equivalent
329: number of spaces.
330: An equivalent number of spaces is defined as the number of spaces
331: output by an
332: .Cm s
333: conversion character with the same field width
334: and precision as the original conversion character or conversion
335: string but with any
1.10 aaron 336: .Ql + ,
337: .Ql \&\ \& ,
338: .Ql #
1.1 deraadt 339: conversion flag characters
340: removed, and referencing a NULL string.
341: .Pp
342: If no format strings are specified, the default display is equivalent
343: to specifying the
344: .Fl x
345: option.
1.21 ! jmc 346: .Sh EXIT STATUS
1.17 jmc 347: .Ex -std hexdump
1.1 deraadt 348: .Sh EXAMPLES
349: Display the input in perusal format:
350: .Bd -literal -offset indent
351: "%06.6_ao " 12/1 "%3_u "
352: "\et\et" "%_p "
353: "\en"
354: .Ed
355: .Pp
356: Implement the \-x option:
357: .Bd -literal -offset indent
358: "%07.7_Ax\en"
359: "%07.7_ax " 8/2 "%04x " "\en"
360: .Ed
1.10 aaron 361: .Sh SEE ALSO
362: .Xr od 1
![[BACK]](/icons/back.gif){kind=icon}
Return to hexdump.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / hexdump