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