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