380 lines
13 KiB
Groff
380 lines
13 KiB
Groff
.\" Copyright (c) 1989, 1990, 1993
|
|
.\" The Regents of the University of California. All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the University of
|
|
.\" California, Berkeley and its contributors.
|
|
.\" 4. Neither the name of the University nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" @(#)hexdump.1 8.2 (Berkeley) 4/18/94
|
|
.\"
|
|
.TH HEXDUMP "1" "April 2013" "util-linux" "User Commands"
|
|
.SH NAME
|
|
hexdump \- display file contents in hexadecimal, decimal, octal, or ascii
|
|
.SH SYNOPSIS
|
|
.B hexdump
|
|
.RI [options] " file" ...
|
|
.SH DESCRIPTION
|
|
The
|
|
.B hexdump
|
|
utility is a filter which displays the specified files, or
|
|
standard input if no files are specified, in a user-specified
|
|
format.
|
|
.SH OPTIONS
|
|
Below, the \fIlength\fR and \fIoffset\fR arguments may be followed by the multiplicative
|
|
suffixes KiB (=1024), MiB (=1024*1024), and so on for GiB, TiB, PiB, EiB, ZiB and YiB
|
|
(the "iB" is optional, e.g. "K" has the same meaning as "KiB"), or the suffixes
|
|
KB (=1000), MB (=1000*1000), and so on for GB, TB, PB, EB, ZB and YB.
|
|
.TP
|
|
\fB\-b\fR, \fB\-\-one\-byte\-octal\fR
|
|
\fIOne-byte octal display\fR. Display the input offset in hexadecimal,
|
|
followed by sixteen space-separated, three-column, zero-filled bytes of input
|
|
data, in octal, per line.
|
|
.TP
|
|
\fB\-c\fR, \fB\-\-one\-byte\-char\fR
|
|
\fIOne-byte character display\fR. Display the input offset in hexadecimal,
|
|
followed by sixteen space-separated, three-column, space-filled characters of
|
|
input data per line.
|
|
.TP
|
|
\fB\-C\fR, \fB\-\-canonical\fR
|
|
\fICanonical hex+ASCII display\fR. Display the input offset in hexadecimal,
|
|
followed by sixteen space-separated, two-column, hexadecimal bytes, followed
|
|
by the same sixteen bytes in
|
|
.B %_p
|
|
format enclosed in
|
|
.RB ' | '
|
|
characters.
|
|
.TP
|
|
\fB\-d\fR, \fB\-\-two\-bytes\-decimal\fR
|
|
\fITwo-byte decimal display\fR. Display the input offset in hexadecimal,
|
|
followed by eight space-separated, five-column, zero-filled, two-byte units
|
|
of input data, in unsigned decimal, per line.
|
|
.TP
|
|
\fB\-e\fR, \fB\-\-format\fR \fIformat_string\fR
|
|
Specify a format string to be used for displaying data.
|
|
.TP
|
|
\fB\-f\fR, \fB\-\-format\-file\fR \fIfile\fR
|
|
Specify a file that contains one or more newline-separated format strings.
|
|
Empty lines and lines whose first non-blank character is a hash mark (\&#)
|
|
are ignored.
|
|
.TP
|
|
\fB\-L\fR, \fB\-\-color\fR[=\fIwhen\fR]
|
|
Accept color units for the output. The optional argument \fIwhen\fP
|
|
can be \fBauto\fR, \fBnever\fR or \fBalways\fR. If the \fIwhen\fR argument is omitted,
|
|
it defaults to \fBauto\fR. The colors can be disabled; for the current built-in default
|
|
see the \fB\-\-help\fR output. See also the \fBColors\fR subsection and
|
|
the \fBCOLORS\fR section below.
|
|
.TP
|
|
\fB\-n\fR, \fB\-\-length\fR \fIlength\fR
|
|
Interpret only
|
|
.I length
|
|
bytes of input.
|
|
.TP
|
|
\fB\-o\fR, \fB\-\-two\-bytes\-octal\fR
|
|
\fITwo-byte octal display\fR. Display the input offset in hexadecimal,
|
|
followed by eight space-separated, six-column, zero-filled, two-byte
|
|
quantities of input data, in octal, per line.
|
|
.TP
|
|
\fB\-s\fR, \fB\-\-skip\fR \fIoffset\fR
|
|
Skip
|
|
.I offset
|
|
bytes from the beginning of the input.
|
|
.TP
|
|
\fB\-v\fR, \fB\-\-no\-squeezing\fR
|
|
The
|
|
.B \-v
|
|
option causes
|
|
.B hexdump
|
|
to display all input data. Without the
|
|
.B \-v
|
|
option, any number of groups of output lines which would be identical to the
|
|
immediately preceding group of output lines (except for the input offsets),
|
|
are replaced with a line comprised of a single asterisk.
|
|
.TP
|
|
\fB\-x\fR, \fB\-\-two\-bytes\-hex\fR
|
|
\fITwo-byte hexadecimal display\fR. Display the input offset in hexadecimal,
|
|
followed by eight space-separated, four-column, zero-filled, two-byte
|
|
quantities of input data, in hexadecimal, per line.
|
|
.TP
|
|
.BR \-V , " \-\-version"
|
|
Display version information and exit.
|
|
.TP
|
|
.BR \-h , " \-\-help"
|
|
Display help text and exit.
|
|
.PP
|
|
For each input file,
|
|
.B hexdump
|
|
sequentially copies the input to standard output, transforming the data
|
|
according to the format strings specified by the
|
|
.B \-e
|
|
and
|
|
.B \-f
|
|
options, in the order that they were specified.
|
|
.SH FORMATS
|
|
A format string contains any number of format units, separated by whitespace.
|
|
A format unit contains up to three items: an iteration count, a byte count,
|
|
and a format.
|
|
.PP
|
|
The iteration count is an optional positive integer, which defaults to one.
|
|
Each format is applied iteration count times.
|
|
.PP
|
|
The byte count is an optional positive integer. If specified it defines the
|
|
number of bytes to be interpreted by each iteration of the format.
|
|
.PP
|
|
If an iteration count and/or a byte count is specified, a single slash must
|
|
be placed after the iteration count and/or before the byte count to
|
|
disambiguate them. Any whitespace before or after the slash is ignored.
|
|
.PP
|
|
The format is required and must be surrounded by double quote (" ") marks.
|
|
It is interpreted as a fprintf-style format string (see
|
|
.BR fprintf (3),
|
|
with the following exceptions:
|
|
.TP
|
|
1.
|
|
An asterisk (*) may not be used as a field width or precision.
|
|
.TP
|
|
2.
|
|
A byte count or field precision
|
|
.I is
|
|
required for each
|
|
.B s
|
|
conversion character (unlike the
|
|
.BR fprintf (3)
|
|
default which prints the entire string if the precision is unspecified).
|
|
.TP
|
|
3.
|
|
The conversion characters
|
|
.BR h , \ l , \ n , \ p ,
|
|
.RB and \ q
|
|
are not supported.
|
|
.TP
|
|
4.
|
|
The single character escape sequences described in the C standard are
|
|
supported:
|
|
.PP
|
|
.RS 13
|
|
.PD 0
|
|
.TP 21
|
|
NULL
|
|
\e0
|
|
.TP
|
|
<alert character>
|
|
\ea
|
|
.TP
|
|
<backspace>
|
|
\eb
|
|
.TP
|
|
<form-feed>
|
|
\ef
|
|
.TP
|
|
<newline>
|
|
\en
|
|
.TP
|
|
<carriage return>
|
|
\er
|
|
.TP
|
|
<tab>
|
|
\et
|
|
.TP
|
|
<vertical tab>
|
|
\ev
|
|
.PD
|
|
.RE
|
|
.PP
|
|
.SS Conversion strings
|
|
The
|
|
.B hexdump
|
|
utility also supports the following additional conversion strings.
|
|
.TP
|
|
.B \&_a[dox]
|
|
Display the input offset, cumulative across input files, of the next byte to
|
|
be displayed. The appended characters
|
|
.BR d ,
|
|
.BR o ,
|
|
and
|
|
.B x
|
|
specify the display base as decimal, octal or hexadecimal respectively.
|
|
.TP
|
|
.B \&_A[dox]
|
|
Identical to the
|
|
.B \&_a
|
|
conversion string except that it is only performed once, when all of the
|
|
input data has been processed.
|
|
.TP
|
|
.B \&_c
|
|
Output characters in the default character set. Non-printing characters are
|
|
displayed in three-character, zero-padded octal, except for those
|
|
representable by standard escape notation (see above), which are displayed as
|
|
two-character strings.
|
|
.TP
|
|
.B \&_p
|
|
Output characters in the default character set. Non-printing characters are
|
|
displayed as a single
|
|
.RB ' \&. '.
|
|
.TP
|
|
.B \&_u
|
|
Output US ASCII characters, with the exception that control characters are
|
|
displayed using the following, lower-case, names. Characters greater than
|
|
0xff, hexadecimal, are displayed as hexadecimal strings.
|
|
.RS 10
|
|
.TS
|
|
tab(|);
|
|
l l l l l l.
|
|
000 nul|001 soh|002 stx|003 etx|004 eot|005 enq
|
|
006 ack|007 bel|008 bs|009 ht|00A lf|00B vt
|
|
00C ff|00D cr|00E so|00F si|010 dle|011 dc1
|
|
012 dc2|013 dc3|014 dc4|015 nak|016 syn|017 etb
|
|
018 can|019 em|01A sub|01B esc|01C fs|01D gs
|
|
01E rs|01F us|0FF del
|
|
.TE
|
|
.SS Colors
|
|
When put at the end of a format specifier, hexdump highlights the
|
|
respective string with the color specified. Conditions, if present, are
|
|
evaluated prior to highlighting.
|
|
.PP
|
|
.B \&_L[color_unit_1,\:color_unit_2,\:...,\:color_unit_n]
|
|
.PP
|
|
The full syntax of a color unit is as follows:
|
|
.PP
|
|
.B [!]COLOR\:[:VALUE]\:[@OFFSET_START[-END]]
|
|
.TP
|
|
.B !
|
|
Negate the condition. Please note that it only makes sense to negate a
|
|
unit if both a value/\:string and an offset are specified. In that case
|
|
the respective output string will be highlighted if and only if the
|
|
value/\:string does not match the one at the offset.
|
|
.TP
|
|
.B COLOR
|
|
One of the 8 basic shell colors.
|
|
.TP
|
|
.B VALUE
|
|
A value to be matched specified in hexadecimal, or octal base, or as a
|
|
string. Please note that the usual C escape sequences are not
|
|
interpreted by hexdump inside the color_units.
|
|
.TP
|
|
.B OFFSET
|
|
An offset or an offset range at which to check for a match. Please note
|
|
that lone OFFSET_START uses the same value as END offset.
|
|
.SS Counters
|
|
The default and supported byte counts for the conversion characters
|
|
are as follows:
|
|
.TP
|
|
.BR \&%_c , \ \&%_p , \ \&%_u , \ \&%c
|
|
One byte counts only.
|
|
.TP
|
|
.BR \&%d , \ \&%i , \ \&%o , \ \&%u , \ \&%X , \ \&%x
|
|
Four byte default, one, two and four byte counts supported.
|
|
.TP
|
|
.BR \&%E , \ \&%e , \ \&%f , \ \&%G , \ \&%g
|
|
Eight byte default, four byte counts supported.
|
|
.PP
|
|
The amount of data interpreted by each format string is the sum of the data
|
|
required by each format unit, which is the iteration count times the byte
|
|
count, or the iteration count times the number of bytes required by the
|
|
format if the byte count is not specified.
|
|
.PP
|
|
The input is manipulated in
|
|
.IR blocks ,
|
|
where a block is defined as the largest amount of data specified by any
|
|
format string. Format strings interpreting less than an input block's worth
|
|
of data, whose last format unit both interprets some number of bytes and does
|
|
not have a specified iteration count, have the iteration count incremented
|
|
until the entire input block has been processed or there is not enough data
|
|
remaining in the block to satisfy the format string.
|
|
.PP
|
|
If, either as a result of user specification or
|
|
.B hexdump
|
|
modifying the iteration count as described above, an iteration count is
|
|
greater than one, no trailing whitespace characters are output during the
|
|
last iteration.
|
|
.PP
|
|
It is an error to specify a byte count as well as multiple conversion
|
|
characters or strings unless all but one of the conversion characters or
|
|
strings is
|
|
.B \&_a
|
|
or
|
|
.BR \&_A .
|
|
.PP
|
|
If, as a result of the specification of the
|
|
.B \-n
|
|
option or end-of-file being reached, input data only partially satisfies a
|
|
format string, the input block is zero-padded sufficiently to display all
|
|
available data (i.e. any format units overlapping the end of data will
|
|
display some number of the zero bytes).
|
|
.PP
|
|
Further output by such format strings is replaced by an equivalent number of
|
|
spaces. An equivalent number of spaces is defined as the number of spaces
|
|
output by an
|
|
.B s
|
|
conversion character with the same field width and precision as the original
|
|
conversion character or conversion string but with any
|
|
.RB ' \&+ ',
|
|
\' \',
|
|
.RB ' \&# '
|
|
conversion flag characters removed, and referencing a NULL string.
|
|
.PP
|
|
If no format strings are specified, the default display is very similar to
|
|
the \fB\-x\fR output format (the \fB\-x\fR option causes more space to be
|
|
used between format units than in the default output).
|
|
.SH "EXIT STATUS"
|
|
.B hexdump
|
|
exits 0 on success and >0 if an error occurred.
|
|
.SH EXAMPLES
|
|
Display the input in perusal format:
|
|
.nf
|
|
"%06.6_ao " 12/1 "%3_u "
|
|
"\et\et" "%_p "
|
|
"\en"
|
|
.nf
|
|
.PP
|
|
Implement the \-x option:
|
|
.nf
|
|
"%07.7_Ax\en"
|
|
"%07.7_ax " 8/2 "%04x " "\en"
|
|
.nf
|
|
.PP
|
|
MBR Boot Signature example: Highlight the addresses cyan and the bytes at
|
|
offsets 510 and 511 green if their value is 0xAA55, red otherwise.
|
|
.nf
|
|
"%07.7_Ax_L[cyan]\en"
|
|
"%07.7_ax_L[cyan] " 8/2 " %04x_L[green:0xAA55@510-511,!red:0xAA55@510-511] " "\en"
|
|
.nf
|
|
.SH COLORS
|
|
Implicit coloring can be disabled by an empty file \fI/etc/terminal-colors.d/hexdump.disable\fR.
|
|
|
|
See
|
|
.BR terminal-colors.d (5)
|
|
for more details about colorization configuration.
|
|
.SH STANDARDS
|
|
The
|
|
.B hexdump
|
|
utility is expected to be IEEE Std 1003.2 ("POSIX.2") compatible.
|
|
.SH AVAILABILITY
|
|
The hexdump command is part of the util-linux package and is available from
|
|
.UR https://\:www.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
|
|
Linux Kernel Archive
|
|
.UE .
|