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