Annotation of src/usr.bin/hexdump/hexdump.1, Revision 1.15
1.15 ! miod 1: .\" $OpenBSD: hexdump.1,v 1.14 2003/06/03 02:56:09 millert 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:
219: .Bd -ragged -offset indent -compact
220: .Bl -column <alert_character>
221: .It NUL \e0
222: .It <alert character> \ea
223: .It <backspace> \eb
224: .It <form-feed> \ef
225: .It <newline> \en
226: .It <carriage return> \er
227: .It <tab> \et
228: .It <vertical tab> \ev
229: .El
230: .Ed
231: .El
232: .Pp
1.8 aaron 233: .Nm
1.5 aaron 234: also supports the following additional conversion strings:
1.1 deraadt 235: .Bl -tag -width Fl
1.7 aaron 236: .It Cm \&_a Ns Op Cm dox
1.1 deraadt 237: Display the input offset, cumulative across input files, of the
238: next byte to be displayed.
239: The appended characters
240: .Cm d ,
241: .Cm o ,
242: and
243: .Cm x
244: specify the display base
245: as decimal, octal or hexadecimal respectively.
1.7 aaron 246: .It Cm \&_A Ns Op Cm dox
1.1 deraadt 247: Identical to the
248: .Cm \&_a
249: conversion string except that it is only performed
250: once, when all of the input data has been processed.
251: .It Cm \&_c
252: Output characters in the default character set.
253: Nonprinting characters are displayed in three character, zero-padded
254: octal, except for those representable by standard escape notation
255: (see above),
256: which are displayed as two character strings.
257: .It Cm _p
258: Output characters in the default character set.
1.10 aaron 259: Nonprinting characters are displayed as a single dot
260: .Ql \&. .
1.1 deraadt 261: .It Cm _u
262: Output US ASCII characters, with the exception that control characters are
263: displayed using the following, lower-case, names.
264: Characters greater than 0xff, hexadecimal, are displayed as hexadecimal
265: strings.
266: .Bl -column \&000_nu \&001_so \&002_st \&003_et \&004_eo
267: .It \&000\ nul\t001\ soh\t002\ stx\t003\ etx\t004\ eot\t005\ enq
268: .It \&006\ ack\t007\ bel\t008\ bs\t009\ ht\t00A\ lf\t00B\ vt
269: .It \&00C\ ff\t00D\ cr\t00E\ so\t00F\ si\t010\ dle\t011\ dc1
270: .It \&012\ dc2\t013\ dc3\t014\ dc4\t015\ nak\t016\ syn\t017\ etb
271: .It \&018\ can\t019\ em\t01A\ sub\t01B\ esc\t01C\ fs\t01D\ gs
272: .It \&01E\ rs\t01F\ us\t0FF\ del
273: .El
274: .El
275: .Pp
276: The default and supported byte counts for the conversion characters
277: are as follows:
278: .Bl -tag -width "Xc,_Xc,_Xc,_Xc,_Xc,_Xc" -offset indent
279: .It Li \&%_c , \&%_p , \&%_u , \&%c
280: One byte counts only.
281: .It Xo
282: .Li \&%d , \&%i , \&%o ,
1.7 aaron 283: .Li \&%u , \&%X , \&%x
1.1 deraadt 284: .Xc
1.13 pvalchev 285: Four byte default, one, two, four and eight byte counts supported.
1.1 deraadt 286: .It Xo
287: .Li \&%E , \&%e , \&%f ,
1.7 aaron 288: .Li \&%G , \&%g
1.1 deraadt 289: .Xc
290: Eight byte default, four byte counts supported.
291: .El
292: .Pp
293: The amount of data interpreted by each format string is the sum of the
294: data required by each format unit, which is the iteration count times the
295: byte count, or the iteration count times the number of bytes required by
296: the format if the byte count is not specified.
297: .Pp
1.10 aaron 298: The input is manipulated in
299: .Dq blocks ,
300: where a block is defined as the
1.1 deraadt 301: largest amount of data specified by any format string.
302: Format strings interpreting less than an input block's worth of data,
303: whose last format unit both interprets some number of bytes and does
1.3 deraadt 304: not have a specified iteration count, have the iteration count
1.1 deraadt 305: incremented until the entire input block has been processed or there
306: is not enough data remaining in the block to satisfy the format string.
307: .Pp
308: If, either as a result of user specification or hexdump modifying
309: the iteration count as described above, an iteration count is
310: greater than one, no trailing whitespace characters are output
311: during the last iteration.
312: .Pp
313: It is an error to specify a byte count as well as multiple conversion
314: characters or strings unless all but one of the conversion characters
315: or strings is
316: .Cm \&_a
317: or
318: .Cm \&_A .
319: .Pp
320: If, as a result of the specification of the
321: .Fl n
322: option or end-of-file being reached, input data only partially
323: satisfies a format string, the input block is zero-padded sufficiently
1.11 aaron 324: to display all available data (i.e., any format units overlapping the
1.1 deraadt 325: end of data will display some number of the zero bytes).
326: .Pp
327: Further output by such format strings is replaced by an equivalent
328: number of spaces.
329: An equivalent number of spaces is defined as the number of spaces
330: output by an
331: .Cm s
332: conversion character with the same field width
333: and precision as the original conversion character or conversion
334: string but with any
1.10 aaron 335: .Ql + ,
336: .Ql \&\ \& ,
337: .Ql #
1.1 deraadt 338: conversion flag characters
339: removed, and referencing a NULL string.
340: .Pp
341: If no format strings are specified, the default display is equivalent
342: to specifying the
343: .Fl x
344: option.
345: .Pp
1.8 aaron 346: .Nm
1.13 pvalchev 347: exits 0 on success and >0 if an error occurred.
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