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