Annotation of src/usr.bin/hexdump/hexdump.1, Revision 1.28
1.28 ! naddy 1: .\" $OpenBSD: hexdump.1,v 1.27 2020/01/16 16:46:47 schwarze 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.28 ! naddy 33: .Dd $Mdocdate: January 16 2020 $
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: .Bk -words
1.18 jmc 42: .Op Fl bCcdovx
1.1 deraadt 43: .Op Fl e Ar format_string
44: .Op Fl f Ar format_file
45: .Op Fl n Ar length
1.18 jmc 46: .Op Fl s Ar offset
47: .Op Ar
1.13 pvalchev 48: .Ek
1.1 deraadt 49: .Sh DESCRIPTION
1.5 aaron 50: The
1.8 aaron 51: .Nm
1.5 aaron 52: utility is a filter which displays the specified files, or
53: the standard input, if no files are specified, in a user-specified
1.1 deraadt 54: format.
55: .Pp
56: The options are as follows:
1.12 aaron 57: .Bl -tag -width Ds
1.1 deraadt 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.
1.18 jmc 63: .It Fl C
64: .Em Canonical hex+ASCII display .
65: Display the input offset in hexadecimal, followed by sixteen
66: space-separated, two column, hexadecimal bytes, followed by the
1.25 bentley 67: same sixteen bytes in %_p format enclosed in
68: .Sq |
69: characters.
1.1 deraadt 70: .It Fl c
71: .Em One-byte character display .
72: Display the input offset in hexadecimal, followed by sixteen
73: space-separated, three column, space-filled, characters of input
74: data per line.
75: .It Fl d
1.5 aaron 76: .Em Two-byte decimal display .
1.1 deraadt 77: Display the input offset in hexadecimal, followed by eight
78: space-separated, five column, zero-filled, two-byte units
79: of input data, in unsigned decimal, per line.
1.7 aaron 80: .It Fl e Ar format_string
1.1 deraadt 81: Specify a format string to be used for displaying data.
1.7 aaron 82: .It Fl f Ar format_file
1.1 deraadt 83: Specify a file that contains one or more newline separated format strings.
84: Empty lines and lines whose first non-blank character is a hash mark
1.10 aaron 85: .Pq Ql #
1.1 deraadt 86: are ignored.
1.7 aaron 87: .It Fl n Ar length
1.1 deraadt 88: Interpret only
89: .Ar length
90: bytes of input.
1.15 miod 91: By default,
92: .Ar length
93: is interpreted as a decimal number.
94: With a leading
95: .Cm 0x
96: or
97: .Cm 0X ,
98: .Ar length
99: is interpreted as a hexadecimal number,
100: otherwise, with a leading
101: .Cm 0 ,
102: .Ar length
103: is interpreted as an octal number.
1.1 deraadt 104: .It Fl o
1.6 aaron 105: .Em Two-byte octal display .
1.1 deraadt 106: Display the input offset in hexadecimal, followed by eight
107: space-separated, six column, zero-filled, two byte quantities of
108: input data, in octal, per line.
1.7 aaron 109: .It Fl s Ar offset
1.1 deraadt 110: Skip
111: .Ar offset
112: bytes from the beginning of the input.
113: By default,
114: .Ar offset
115: is interpreted as a decimal number.
116: With a leading
117: .Cm 0x
118: or
119: .Cm 0X ,
120: .Ar offset
121: is interpreted as a hexadecimal number,
122: otherwise, with a leading
123: .Cm 0 ,
124: .Ar offset
125: is interpreted as an octal number.
126: Appending the character
127: .Cm b ,
128: .Cm k ,
129: or
130: .Cm m
131: to
132: .Ar offset
133: causes it to be interpreted as a multiple of
134: .Li 512 ,
135: .Li 1024 ,
136: or
137: .Li 1048576 ,
138: respectively.
139: .It Fl v
140: The
141: .Fl v
142: option causes hexdump to display all input data.
143: Without the
144: .Fl v
145: option, any number of groups of output lines, which would be
146: identical to the immediately preceding group of output lines (except
147: for the input offsets), are replaced with a line comprised of a
1.10 aaron 148: single asterisk
149: .Pq Ql * .
1.1 deraadt 150: .It Fl x
1.6 aaron 151: .Em Two-byte hexadecimal display .
1.1 deraadt 152: Display the input offset in hexadecimal, followed by eight, space
153: separated, four column, zero-filled, two-byte quantities of input
154: data, in hexadecimal, per line.
155: .El
156: .Pp
157: For each input file,
1.8 aaron 158: .Nm
1.1 deraadt 159: sequentially copies the input to standard output, transforming the
160: data according to the format strings specified by the
161: .Fl e
162: and
163: .Fl f
164: options, in the order that they were specified.
165: .Ss Formats
166: A format string contains any number of format units, separated by
167: whitespace.
168: A format unit contains up to three items: an iteration count, a byte
169: count, and a format.
170: .Pp
171: The iteration count is an optional positive integer, which defaults to
172: one.
173: Each format is applied iteration count times.
174: .Pp
175: The byte count is an optional positive integer.
1.28 ! naddy 176: If specified, it defines the number of bytes to be interpreted by
1.1 deraadt 177: each iteration of the format.
178: .Pp
179: If an iteration count and/or a byte count is specified, a single slash
1.10 aaron 180: .Pq Sq /
1.1 deraadt 181: must be placed after the iteration count and/or before the byte count
182: to disambiguate them.
183: Any whitespace before or after the slash is ignored.
184: .Pp
185: The format is required and must be surrounded by double quote
1.10 aaron 186: .Pq \&"\& \&"
1.22 jmc 187: marks
188: (the quote mark is a special character in many shell programs,
189: and may have to be escaped from the shell).
1.13 pvalchev 190: It is interpreted as a fprintf-style format string (see
1.1 deraadt 191: .Xr fprintf 3 ) ,
192: with the
193: following exceptions:
194: .Bl -bullet -offset indent
195: .It
196: An asterisk (*) may not be used as a field width or precision.
197: .It
198: A byte count or field precision
199: .Em is
1.10 aaron 200: required for each
201: .Sq s
202: conversion character (unlike the
1.1 deraadt 203: .Xr fprintf 3
204: default which prints the entire string if the precision is unspecified).
205: .It
1.10 aaron 206: The conversion characters
207: .Sq h ,
1.13 pvalchev 208: .Sq l ,
1.10 aaron 209: .Sq n ,
1.13 pvalchev 210: .Sq p ,
1.10 aaron 211: and
1.13 pvalchev 212: .Sq q
1.10 aaron 213: are not supported.
1.1 deraadt 214: .It
215: The single character escape sequences
216: described in the C standard are supported:
1.16 jmc 217: .Pp
1.17 jmc 218: .Bl -tag -width "Xalert characterXXX" -offset indent -compact
1.16 jmc 219: .It NUL
220: \e0
221: .It Aq alert character
222: \ea
223: .It Aq backspace
224: \eb
225: .It Aq form-feed
226: \ef
227: .It Aq newline
228: \en
229: .It Aq carriage return
230: \er
231: .It Aq tab
232: \et
233: .It Aq vertical tab
234: \ev
1.1 deraadt 235: .El
236: .El
237: .Pp
1.8 aaron 238: .Nm
1.5 aaron 239: also supports the following additional conversion strings:
1.27 schwarze 240: .Bl -tag -width _A[dox]
1.7 aaron 241: .It Cm \&_a Ns Op Cm dox
1.1 deraadt 242: Display the input offset, cumulative across input files, of the
243: next byte to be displayed.
244: The appended characters
245: .Cm d ,
246: .Cm o ,
247: and
248: .Cm x
249: specify the display base
250: as decimal, octal or hexadecimal respectively.
1.7 aaron 251: .It Cm \&_A Ns Op Cm dox
1.1 deraadt 252: Identical to the
253: .Cm \&_a
254: conversion string except that it is only performed
255: once, when all of the input data has been processed.
256: .It Cm \&_c
257: Output characters in the default character set.
258: Nonprinting characters are displayed in three character, zero-padded
259: octal, except for those representable by standard escape notation
260: (see above),
261: which are displayed as two character strings.
262: .It Cm _p
263: Output characters in the default character set.
1.10 aaron 264: Nonprinting characters are displayed as a single dot
265: .Ql \&. .
1.1 deraadt 266: .It Cm _u
267: Output US ASCII characters, with the exception that control characters are
268: displayed using the following, lower-case, names.
1.24 otto 269: Other non-printable characters are displayed as hexadecimal strings.
270: .Bd -literal -offset 3n
271: 000 nul 001 soh 002 stx 003 etx 004 eot 005 enq
272: 006 ack 007 bel 008 bs 009 ht 00A lf 00B vt
273: 00C ff 00D cr 00E so 00F si 010 dle 011 dc1
274: 012 dc2 013 dc3 014 dc4 015 nak 016 syn 017 etb
275: 018 can 019 em 01A sub 01B esc 01C fs 01D gs
276: 01E rs 01F us 07F del
277: .Ed
1.1 deraadt 278: .El
279: .Pp
280: The default and supported byte counts for the conversion characters
281: are as follows:
282: .Bl -tag -width "Xc,_Xc,_Xc,_Xc,_Xc,_Xc" -offset indent
283: .It Li \&%_c , \&%_p , \&%_u , \&%c
284: One byte counts only.
285: .It Xo
286: .Li \&%d , \&%i , \&%o ,
1.7 aaron 287: .Li \&%u , \&%X , \&%x
1.1 deraadt 288: .Xc
1.13 pvalchev 289: Four byte default, one, two, four and eight byte counts supported.
1.1 deraadt 290: .It Xo
291: .Li \&%E , \&%e , \&%f ,
1.7 aaron 292: .Li \&%G , \&%g
1.1 deraadt 293: .Xc
294: Eight byte default, four byte counts supported.
295: .El
296: .Pp
297: The amount of data interpreted by each format string is the sum of the
298: data required by each format unit, which is the iteration count times the
299: byte count, or the iteration count times the number of bytes required by
300: the format if the byte count is not specified.
301: .Pp
1.10 aaron 302: The input is manipulated in
303: .Dq blocks ,
304: where a block is defined as the
1.1 deraadt 305: largest amount of data specified by any format string.
306: Format strings interpreting less than an input block's worth of data,
307: whose last format unit both interprets some number of bytes and does
1.3 deraadt 308: not have a specified iteration count, have the iteration count
1.1 deraadt 309: incremented until the entire input block has been processed or there
310: is not enough data remaining in the block to satisfy the format string.
311: .Pp
312: If, either as a result of user specification or hexdump modifying
313: the iteration count as described above, an iteration count is
314: greater than one, no trailing whitespace characters are output
315: during the last iteration.
316: .Pp
317: It is an error to specify a byte count as well as multiple conversion
318: characters or strings unless all but one of the conversion characters
319: or strings is
320: .Cm \&_a
321: or
322: .Cm \&_A .
323: .Pp
324: If, as a result of the specification of the
325: .Fl n
326: option or end-of-file being reached, input data only partially
327: satisfies a format string, the input block is zero-padded sufficiently
1.11 aaron 328: to display all available data (i.e., any format units overlapping the
1.1 deraadt 329: end of data will display some number of the zero bytes).
330: .Pp
331: Further output by such format strings is replaced by an equivalent
332: number of spaces.
333: An equivalent number of spaces is defined as the number of spaces
334: output by an
335: .Cm s
336: conversion character with the same field width
337: and precision as the original conversion character or conversion
338: string but with any
1.10 aaron 339: .Ql + ,
340: .Ql \&\ \& ,
341: .Ql #
1.1 deraadt 342: conversion flag characters
343: removed, and referencing a NULL string.
344: .Pp
345: If no format strings are specified, the default display is equivalent
346: to specifying the
347: .Fl x
348: option.
1.21 jmc 349: .Sh EXIT STATUS
1.17 jmc 350: .Ex -std hexdump
1.1 deraadt 351: .Sh EXAMPLES
1.22 jmc 352: Display characters using a fieldwidth of 4,
353: and using special names for control characters:
354: .Pp
355: .Dl $ hexdump -e '"%4_u"' file
356: .Pp
357: An example file for use with the
358: .Fl f
359: option, to display the input in perusal format:
1.1 deraadt 360: .Bd -literal -offset indent
361: "%06.6_ao " 12/1 "%3_u "
362: "\et\et" "%_p "
363: "\en"
364: .Ed
365: .Pp
1.22 jmc 366: An example file for use with the
367: .Fl f
368: option, which implements the equivalent of the
369: .Fl x
370: option:
1.1 deraadt 371: .Bd -literal -offset indent
372: "%07.7_Ax\en"
1.23 otto 373: "%07.7_ax " 8/2 " %04x " "\en"
1.1 deraadt 374: .Ed
1.10 aaron 375: .Sh SEE ALSO
376: .Xr od 1
1.26 schwarze 377: .Sh HISTORY
378: The
379: .Nm
380: utility first appeared in
381: .Bx 4.3 Reno .
![[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