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