]> git.ipfire.org Git - thirdparty/util-linux.git/blame - text-utils/hexdump.1
libfdisk: (dos) accept start for log.partitions on template
[thirdparty/util-linux.git] / text-utils / hexdump.1
CommitLineData
6dbe3af9
KZ
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.\"
3a60b1c2 32.\" @(#)hexdump.1 8.2 (Berkeley) 4/18/94
6dbe3af9 33.\"
cdeb4292 34.TH HEXDUMP "1" "April 2013" "util-linux" "User Commands"
7570e15a 35.SH NAME
07990fdc 36hexdump \- display file contents in hexadecimal, decimal, octal, or ascii
7570e15a
SK
37.SH SYNOPSIS
38.B hexdump
1f94a78c 39.RI [options] " file" ...
7570e15a 40.SH DESCRIPTION
5bcd986e 41The
7570e15a 42.B hexdump
5bcd986e
BS
43utility is a filter which displays the specified files, or
44standard input if no files are specified, in a user-specified
6dbe3af9 45format.
7570e15a 46.SH OPTIONS
1f94a78c
BS
47Below, the \fIlength\fR and \fIoffset\fR arguments may be followed by the multiplicative
48suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB
49(the "iB" is optional, e.g. "K" has the same meaning as "KiB"), or the suffixes
50KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
7570e15a 51.TP
cdeb4292 52\fB\-b\fR, \fB\-\-one\-byte\-octal\fR
7570e15a
SK
53\fIOne-byte octal display\fR. Display the input offset in hexadecimal,
54followed by sixteen space-separated, three-column, zero-filled bytes of input
55data, in octal, per line.
56.TP
cdeb4292 57\fB\-c\fR, \fB\-\-one\-byte\-char\fR
7570e15a
SK
58\fIOne-byte character display\fR. Display the input offset in hexadecimal,
59followed by sixteen space-separated, three-column, space-filled characters of
60input data per line.
61.TP
cdeb4292 62\fB\-C\fR, \fB\-\-canonical\fR
7570e15a
SK
63\fICanonical hex+ASCII display\fR. Display the input offset in hexadecimal,
64followed by sixteen space-separated, two-column, hexadecimal bytes, followed
65by the same sixteen bytes in
66.B %_p
67format enclosed in
68.RB ' | '
69characters.
70.TP
cdeb4292 71\fB\-d\fR, \fB\-\-two\-bytes\-decimal\fR
7570e15a
SK
72\fITwo-byte decimal display\fR. Display the input offset in hexadecimal,
73followed by eight space-separated, five-column, zero-filled, two-byte units
6dbe3af9 74of input data, in unsigned decimal, per line.
7570e15a 75.TP
cdeb4292 76\fB\-e\fR, \fB\-\-format\fR \fIformat_string\fR
6dbe3af9 77Specify a format string to be used for displaying data.
7570e15a 78.TP
1f94a78c
BS
79\fB\-f\fR, \fB\-\-format\-file\fR \fIfile\fR
80Specify a file that contains one or more newline-separated format strings.
7570e15a 81Empty lines and lines whose first non-blank character is a hash mark (\&#)
6dbe3af9 82are ignored.
7570e15a 83.TP
1f94a78c 84\fB\-L\fR, \fB\-\-color\fR[=\fIwhen\fR]
5d51dc2a 85Accept color units for the output. The optional argument \fIwhen\fP
1f94a78c 86can be \fBauto\fR, \fBnever\fR or \fBalways\fR. If the \fIwhen\fR argument is omitted,
e8cf378e
BS
87it defaults to \fBauto\fR. The colors can be disabled; for the current built-in default
88see the \fB\-\-help\fR output. See also the \fBColors\fR subsection and
89the \fBCOLORS\fR section below.
1f94a78c 90.TP
cdeb4292 91\fB\-n\fR, \fB\-\-length\fR \fIlength\fR
6dbe3af9 92Interpret only
7570e15a 93.I length
6dbe3af9 94bytes of input.
7570e15a 95.TP
cdeb4292 96\fB\-o\fR, \fB\-\-two\-bytes\-octal\fR
7570e15a
SK
97\fITwo-byte octal display\fR. Display the input offset in hexadecimal,
98followed by eight space-separated, six-column, zero-filled, two-byte
99quantities of input data, in octal, per line.
100.TP
cdeb4292 101\fB\-s\fR, \fB\-\-skip\fR \fIoffset\fR
6dbe3af9 102Skip
7570e15a 103.I offset
6ad533db 104bytes from the beginning of the input.
7570e15a 105.TP
cdeb4292 106\fB\-v\fR, \fB\-\-no\-squeezing\fR
6dbe3af9 107The
7570e15a 108.B \-v
5bcd986e 109option causes
7570e15a
SK
110.B hexdump
111to display all input data. Without the
112.B \-v
113option, any number of groups of output lines which would be identical to the
114immediately preceding group of output lines (except for the input offsets),
115are replaced with a line comprised of a single asterisk.
116.TP
cdeb4292 117\fB\-x\fR, \fB\-\-two\-bytes\-hex\fR
7570e15a
SK
118\fITwo-byte hexadecimal display\fR. Display the input offset in hexadecimal,
119followed by eight space-separated, four-column, zero-filled, two-byte
120quantities of input data, in hexadecimal, per line.
07990fdc
BS
121.TP
122.BR \-V , " \-\-version"
123Display version information and exit.
124.TP
125.BR \-h , " \-\-help"
126Display help text and exit.
7570e15a 127.PP
6dbe3af9 128For each input file,
7570e15a
SK
129.B hexdump
130sequentially copies the input to standard output, transforming the data
131according to the format strings specified by the
132.B \-e
6dbe3af9 133and
7570e15a 134.B \-f
6dbe3af9 135options, in the order that they were specified.
7570e15a
SK
136.SH FORMATS
137A format string contains any number of format units, separated by whitespace.
138A format unit contains up to three items: an iteration count, a byte count,
139and a format.
140.PP
141The iteration count is an optional positive integer, which defaults to one.
6dbe3af9 142Each format is applied iteration count times.
7570e15a
SK
143.PP
144The byte count is an optional positive integer. If specified it defines the
145number of bytes to be interpreted by each iteration of the format.
146.PP
147If an iteration count and/or a byte count is specified, a single slash must
148be placed after the iteration count and/or before the byte count to
149disambiguate them. Any whitespace before or after the slash is ignored.
150.PP
151The format is required and must be surrounded by double quote (" ") marks.
6dbe3af9 152It is interpreted as a fprintf-style format string (see
7570e15a
SK
153.BR fprintf (3),
154with the following exceptions:
155.TP
1561.
6dbe3af9 157An asterisk (*) may not be used as a field width or precision.
7570e15a
SK
158.TP
1592.
6dbe3af9 160A byte count or field precision
7570e15a
SK
161.I is
162required for each
163.B s
164conversion character (unlike the
165.BR fprintf (3)
6dbe3af9 166default which prints the entire string if the precision is unspecified).
7570e15a
SK
167.TP
1683.
169The conversion characters
170.BR h , \ l , \ n , \ p ,
171.RB and \ q
172are not supported.
173.TP
1744.
175The single character escape sequences described in the C standard are
176supported:
177.PP
178.RS 13
179.PD 0
180.TP 21
181NULL
182\e0
183.TP
184<alert character>
185\ea
186.TP
187<backspace>
188\eb
189.TP
190<form-feed>
191\ef
192.TP
193<newline>
194\en
195.TP
196<carriage return>
197\er
198.TP
199<tab>
200\et
201.TP
202<vertical tab>
203\ev
204.PD
205.RE
206.PP
207.SS Conversion strings
5bcd986e 208The
7570e15a
SK
209.B hexdump
210utility also supports the following additional conversion strings.
211.TP
212.B \&_a[dox]
213Display the input offset, cumulative across input files, of the next byte to
214be displayed. The appended characters
215.BR d ,
216.BR o ,
6dbe3af9 217and
7570e15a
SK
218.B x
219specify the display base as decimal, octal or hexadecimal respectively.
220.TP
221.B \&_A[dox]
6dbe3af9 222Identical to the
7570e15a
SK
223.B \&_a
224conversion string except that it is only performed once, when all of the
225input data has been processed.
226.TP
227.B \&_c
d35df4db 228Output characters in the default character set. Non-printing characters are
7570e15a
SK
229displayed in three-character, zero-padded octal, except for those
230representable by standard escape notation (see above), which are displayed as
231two-character strings.
232.TP
233.B \&_p
d35df4db 234Output characters in the default character set. Non-printing characters are
7570e15a
SK
235displayed as a single
236.RB ' \&. '.
237.TP
238.B \&_u
6dbe3af9 239Output US ASCII characters, with the exception that control characters are
7570e15a
SK
240displayed using the following, lower-case, names. Characters greater than
2410xff, hexadecimal, are displayed as hexadecimal strings.
100af003
SK
242.RS 10
243.TS
244tab(|);
245left l l l l l.
246000 nul|001 soh|002 stx|003 etx|004 eot|005 enq
247006 ack|007 bel|008 bs|009 ht|00A lf|00B vt
24800C ff|00D cr|00E so|00F si|010 dle|011 dc1
249012 dc2|013 dc3|014 dc4|015 nak|016 syn|017 etb
250018 can|019 em|01A sub|01B esc|01C fs|01D gs
25101E rs|01F us|0FF del
252.TE
098ab077 253.SS Colors
100af003
SK
254When put at the end of a format specifier, hexdump highlights the
255respective string with the color specified. Conditions, if present, are
256evaluated prior to highlighting.
257.PP
258.B \&_L[color_unit_1,\:color_unit_2,\:...,\:color_unit_n]
259.PP
098ab077 260The full syntax of a color unit is as follows:
100af003
SK
261.PP
262.B [!]COLOR\:[:VALUE]\:[@OFFSET_START[-END]]
098ab077
OO
263.TP
264.B !
100af003
SK
265Negate the condition. Please note that it only makes sense to negate a
266unit if both a value/\:string and an offset are specified. In that case
267the respective output string will be highlighted if and only if the
268value/\:string does not match the one at the offset.
269.TP
098ab077
OO
270.BR COLOR
271One of the 8 basic shell colors.
100af003
SK
272.TP
273.B VALUE
274A value to be matched specified in hexadecimal, or octal base, or as a
275string. Please note that the usual C escape sequences are not
276interpreted by hexdump inside the color_units.
277.TP
278.B OFFSET
279An offset or an offset range at which to check for a match. Please note
3bf7ede9 280that lone OFFSET_START uses the same value as END offset.
7570e15a 281.SS Counters
6dbe3af9
KZ
282The default and supported byte counts for the conversion characters
283are as follows:
7570e15a
SK
284.TP
285.BR \&%_c , \ \&%_p , \ \&%_u , \ \&%c
6dbe3af9 286One byte counts only.
7570e15a
SK
287.TP
288.BR \&%d , \ \&%i , \ \&%o , \ \&%u , \ \&%X , \ \&%x
6dbe3af9 289Four byte default, one, two and four byte counts supported.
7570e15a
SK
290.TP
291.BR \&%E , \ \&%e , \ \&%f , \ \&%G , \ \&%g
6dbe3af9 292Eight byte default, four byte counts supported.
7570e15a
SK
293.PP
294The amount of data interpreted by each format string is the sum of the data
295required by each format unit, which is the iteration count times the byte
296count, or the iteration count times the number of bytes required by the
297format if the byte count is not specified.
298.PP
299The input is manipulated in
300.IR blocks ,
301where a block is defined as the largest amount of data specified by any
302format string. Format strings interpreting less than an input block's worth
303of data, whose last format unit both interprets some number of bytes and does
304not have a specified iteration count, have the iteration count incremented
305until the entire input block has been processed or there is not enough data
306remaining in the block to satisfy the format string.
307.PP
5bcd986e 308If, either as a result of user specification or
7570e15a 309.B hexdump
5bcd986e 310modifying the iteration count as described above, an iteration count is
7570e15a
SK
311greater than one, no trailing whitespace characters are output during the
312last iteration.
313.PP
6dbe3af9 314It is an error to specify a byte count as well as multiple conversion
7570e15a
SK
315characters or strings unless all but one of the conversion characters or
316strings is
317.B \&_a
6dbe3af9 318or
7570e15a
SK
319.BR \&_A .
320.PP
6dbe3af9 321If, as a result of the specification of the
7570e15a
SK
322.B \-n
323option or end-of-file being reached, input data only partially satisfies a
324format string, the input block is zero-padded sufficiently to display all
325available data (i.e. any format units overlapping the end of data will
326display some number of the zero bytes).
327.PP
328Further output by such format strings is replaced by an equivalent number of
329spaces. An equivalent number of spaces is defined as the number of spaces
6dbe3af9 330output by an
7570e15a
SK
331.B s
332conversion character with the same field width and precision as the original
333conversion character or conversion string but with any
334.RB ' \&+ ',
335\' \',
336.RB ' \&# '
337conversion flag characters removed, and referencing a NULL string.
338.PP
e8cf378e
BS
339If no format strings are specified, the default display is very similar to
340the \fB\-x\fR output format (the \fB\-x\fR option causes more space to be
341used between format units than in the default output).
7570e15a
SK
342.SH "EXIT STATUS"
343.B hexdump
6dbe3af9 344exits 0 on success and >0 if an error occurred.
7570e15a 345.SH EXAMPLES
6dbe3af9 346Display the input in perusal format:
7570e15a
SK
347.nf
348 "%06.6_ao " 12/1 "%3_u "
349 "\et\et" "%_p "
350 "\en"
351.nf
352.PP
6dbe3af9 353Implement the \-x option:
7570e15a
SK
354.nf
355 "%07.7_Ax\en"
356 "%07.7_ax " 8/2 "%04x " "\en"
357.nf
098ab077 358.PP
100af003
SK
359MBR Boot Signature example: Highlight the addresses cyan and the bytes at
360offsets 510 and 511 green if their value is 0xAA55, red otherwise.
098ab077
OO
361.nf
362 "%07.7_Ax_L[cyan]\en"
363 "%07.7_ax_L[cyan] " 8/2 " %04x_L[green:0xAA55@510-511,!red:0xAA55@510-511] " "\en"
364.nf
60ec67ff 365.SH COLORS
052e512a 366Implicit coloring can be disabled by an empty file \fI/etc/terminal-colors.d/hexdump.disable\fR.
60ec67ff 367
052e512a
KZ
368See
369.BR terminal-colors.d (5)
370for more details about colorization configuration.
7570e15a 371.SH STANDARDS
ffc43748 372The
7570e15a
SK
373.B hexdump
374utility is expected to be IEEE Std 1003.2 ("POSIX.2") compatible.
375.SH AVAILABILITY
601d12fb 376The hexdump command is part of the util-linux package and is available from
d673b74e 377.UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
7570e15a
SK
378Linux Kernel Archive
379.UE .