docs: align hexdump.1 with howto-man-page.txt
Signed-off-by: Sami Kerola <kerolasa@iki.fi>
This commit is contained in:
Sami Kerola
parent
e6ed925d41
commit
7570e15a1d
|
|
@ -31,319 +31,312 @@
|
|||
.\"
|
||||
.\" from: @(#)hexdump.1 8.2 (Berkeley) 4/18/94
|
||||
.\"
|
||||
.Dd July 2009 " "
|
||||
.Dt HEXDUMP(1) "" "User Commands"
|
||||
.Os util-linux
|
||||
.Sh NAME
|
||||
.Nm hexdump
|
||||
.Nd display file contents in ascii, decimal, hexadecimal, or octal
|
||||
.Sh SYNOPSIS
|
||||
.Nm
|
||||
.Op Fl bcCdovx
|
||||
.Bk -words
|
||||
.Op Fl e Ar format_string
|
||||
.Ek
|
||||
.Bk -words
|
||||
.Op Fl f Ar format_file
|
||||
.Ek
|
||||
.Bk -words
|
||||
.Op Fl n Ar length
|
||||
.Ek
|
||||
.Bk -words
|
||||
.Op Fl s Ar skip
|
||||
.Ek
|
||||
.Ar file ...
|
||||
.Sh DESCRIPTION
|
||||
.TH HEXDUMP "1" "September 2011" "util-linux" "User Commands"
|
||||
.SH NAME
|
||||
hexdump \- display file contents in ascii, decimal, hexadecimal, or octal
|
||||
.SH SYNOPSIS
|
||||
.B hexdump
|
||||
[options] file [...]
|
||||
.SH DESCRIPTION
|
||||
The
|
||||
.Nm
|
||||
.B hexdump
|
||||
utility is a filter which displays the specified files, or
|
||||
standard input if no files are specified, in a user-specified
|
||||
format.
|
||||
.Pp
|
||||
The options are as follows:
|
||||
.Bl -tag -width Fl
|
||||
.It Fl b
|
||||
.Em One-byte octal display .
|
||||
Display the input offset in hexadecimal, followed by sixteen
|
||||
space-separated, three-column, zero-filled bytes of input data,
|
||||
in octal, per line.
|
||||
.It Fl c
|
||||
.Em One-byte character display .
|
||||
Display the input offset in hexadecimal, followed by sixteen
|
||||
space-separated, three-column, space-filled characters of input
|
||||
data per line.
|
||||
.It Fl C
|
||||
.Em Canonical hex+ASCII display .
|
||||
Display the input offset in hexadecimal, followed by sixteen
|
||||
space-separated, two-column, hexadecimal bytes, followed by the
|
||||
same sixteen bytes in %_p format enclosed in ``|'' characters.
|
||||
.It Fl d
|
||||
.Em Two-byte decimal display .
|
||||
Display the input offset in hexadecimal, followed by eight
|
||||
space-separated, five-column, zero-filled, two-byte units
|
||||
.SH OPTIONS
|
||||
.TP
|
||||
.B \-b
|
||||
\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
|
||||
.B \-c
|
||||
\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
|
||||
.B \-C
|
||||
\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
|
||||
.B \-d
|
||||
\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.
|
||||
.It Fl e Ar format_string
|
||||
.TP
|
||||
.BI \-e \ format_string
|
||||
Specify a format string to be used for displaying data.
|
||||
.It Fl f Ar format_file
|
||||
.TP
|
||||
.BI \-f \ format_file
|
||||
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
|
||||
.Pf ( Cm \&# )
|
||||
Empty lines and lines whose first non-blank character is a hash mark (\&#)
|
||||
are ignored.
|
||||
.It Fl n Ar length
|
||||
.TP
|
||||
.BI \-n \ length
|
||||
Interpret only
|
||||
.Ar length
|
||||
.I length
|
||||
bytes of input.
|
||||
.It Fl o
|
||||
.Em Two-byte octal display .
|
||||
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.
|
||||
.It Fl s Ar offset
|
||||
.TP
|
||||
.B \-o
|
||||
\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
|
||||
.BI \-s \ offset
|
||||
Skip
|
||||
.Ar offset
|
||||
bytes from the beginning of the input.
|
||||
By default,
|
||||
.Ar offset
|
||||
is interpreted as a decimal number.
|
||||
With a leading
|
||||
.Cm 0x
|
||||
.I offset
|
||||
bytes from the beginning of the input. By default,
|
||||
.I offset
|
||||
is interpreted as a decimal number. With a leading
|
||||
.B 0x
|
||||
or
|
||||
.Cm 0X ,
|
||||
.Ar offset
|
||||
is interpreted as a hexadecimal number,
|
||||
otherwise, with a leading
|
||||
.Cm 0 ,
|
||||
.Ar offset
|
||||
is interpreted as an octal number.
|
||||
Appending the character
|
||||
.Cm b ,
|
||||
.Cm k ,
|
||||
.BR 0X ,
|
||||
.I offset
|
||||
is interpreted as a hexadecimal number, otherwise, with a leading
|
||||
.BR 0 ,
|
||||
.I offset
|
||||
is interpreted as an octal number. Appending the character
|
||||
.BR b ,
|
||||
.BR k ,
|
||||
or
|
||||
.Cm m
|
||||
.B m
|
||||
to
|
||||
.Ar offset
|
||||
.I offset
|
||||
causes it to be interpreted as a multiple of
|
||||
.Li 512 ,
|
||||
.Li 1024 ,
|
||||
.IR 512 ,
|
||||
.IR 1024 ,
|
||||
or
|
||||
.Li 1048576 ,
|
||||
.IR 1048576 ,
|
||||
respectively.
|
||||
.It Fl v
|
||||
.TP
|
||||
.B \-v
|
||||
The
|
||||
.Fl v
|
||||
.B \-v
|
||||
option causes
|
||||
.Nm
|
||||
to display all input data.
|
||||
Without the
|
||||
.Fl 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.
|
||||
.It Fl x
|
||||
.Em Two-byte hexadecimal display .
|
||||
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.
|
||||
.El
|
||||
.Pp
|
||||
.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
|
||||
.B \-x
|
||||
\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.
|
||||
.PP
|
||||
For each input file,
|
||||
.Nm
|
||||
sequentially copies the input to standard output, transforming the
|
||||
data according to the format strings specified by the
|
||||
.Fl e
|
||||
.B hexdump
|
||||
sequentially copies the input to standard output, transforming the data
|
||||
according to the format strings specified by the
|
||||
.B \-e
|
||||
and
|
||||
.Fl f
|
||||
.B \-f
|
||||
options, in the order that they were specified.
|
||||
.Ss 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.
|
||||
.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.
|
||||
.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
|
||||
.Xr fprintf 3 ) ,
|
||||
with the
|
||||
following exceptions:
|
||||
.Bl -bullet -offset indent
|
||||
.It
|
||||
.BR fprintf (3),
|
||||
with the following exceptions:
|
||||
.TP
|
||||
1.
|
||||
An asterisk (*) may not be used as a field width or precision.
|
||||
.It
|
||||
.TP
|
||||
2.
|
||||
A byte count or field precision
|
||||
.Em is
|
||||
required for each ``s'' conversion
|
||||
character (unlike the
|
||||
.Xr fprintf 3
|
||||
.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).
|
||||
.It
|
||||
The conversion characters ``h'', ``l'', ``n'', ``p'' and ``q'' are
|
||||
not supported.
|
||||
.It
|
||||
The single character escape sequences
|
||||
described in the C standard are supported:
|
||||
.Bd -ragged -offset indent -compact
|
||||
.Bl -column <alert_character>
|
||||
.It NUL \e0
|
||||
.It <alert character> \ea
|
||||
.It <backspace> \eb
|
||||
.It <form-feed> \ef
|
||||
.It <newline> \en
|
||||
.It <carriage return> \er
|
||||
.It <tab> \et
|
||||
.It <vertical tab> \ev
|
||||
.El
|
||||
.Ed
|
||||
.El
|
||||
.Pp
|
||||
.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
|
||||
.Nm
|
||||
utility also supports the following additional conversion strings:
|
||||
.Bl -tag -width Fl
|
||||
.It Cm \&_a Ns Op Cm dox
|
||||
Display the input offset, cumulative across input files, of the
|
||||
next byte to be displayed.
|
||||
The appended characters
|
||||
.Cm d ,
|
||||
.Cm o ,
|
||||
.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
|
||||
.Cm x
|
||||
specify the display base
|
||||
as decimal, octal or hexadecimal respectively.
|
||||
.It Cm \&_A Ns Op Cm dox
|
||||
.B x
|
||||
specify the display base as decimal, octal or hexadecimal respectively.
|
||||
.TP
|
||||
.B \&_A[dox]
|
||||
Identical to the
|
||||
.Cm \&_a
|
||||
conversion string except that it is only performed
|
||||
once, when all of the input data has been processed.
|
||||
.It Cm \&_c
|
||||
Output characters in the default character set.
|
||||
Nonprinting 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.
|
||||
.It Cm _p
|
||||
Output characters in the default character set.
|
||||
Nonprinting characters are displayed as a single
|
||||
.Dq Cm \&. .
|
||||
.It Cm _u
|
||||
.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. Nonprinting 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. Nonprinting 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.
|
||||
.Bl -column \&000_nu \&001_so \&002_st \&003_et \&004_eo
|
||||
.It \&000\ nul\t001\ soh\t002\ stx\t003\ etx\t004\ eot\t005\ enq
|
||||
.It \&006\ ack\t007\ bel\t008\ bs\t009\ ht\t00A\ lf\t00B\ vt
|
||||
.It \&00C\ ff\t00D\ cr\t00E\ so\t00F\ si\t010\ dle\t011\ dc1
|
||||
.It \&012\ dc2\t013\ dc3\t014\ dc4\t015\ nak\t016\ syn\t017\ etb
|
||||
.It \&018\ can\t019\ em\t01A\ sub\t01B\ esc\t01C\ fs\t01D\ gs
|
||||
.It \&01E\ rs\t01F\ us\t0FF\ del
|
||||
.El
|
||||
.El
|
||||
.Pp
|
||||
displayed using the following, lower-case, names. Characters greater than
|
||||
0xff, hexadecimal, are displayed as hexadecimal strings.
|
||||
.PP
|
||||
.nf
|
||||
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
|
||||
.nf
|
||||
.SS Counters
|
||||
The default and supported byte counts for the conversion characters
|
||||
are as follows:
|
||||
.Bl -tag -width "Xc,_Xc,_Xc,_Xc,_Xc,_Xc" -offset indent
|
||||
.It Li \&%_c , \&%_p , \&%_u , \&%c
|
||||
.TP
|
||||
.BR \&%_c , \ \&%_p , \ \&%_u , \ \&%c
|
||||
One byte counts only.
|
||||
.It Xo
|
||||
.Li \&%d , \&%i , \&%o ,
|
||||
.Li \&%u , \&%X , \&%x
|
||||
.Xc
|
||||
.TP
|
||||
.BR \&%d , \ \&%i , \ \&%o , \ \&%u , \ \&%X , \ \&%x
|
||||
Four byte default, one, two and four byte counts supported.
|
||||
.It Xo
|
||||
.Li \&%E , \&%e , \&%f ,
|
||||
.Li \&%G , \&%g
|
||||
.Xc
|
||||
.TP
|
||||
.BR \&%E , \ \&%e , \ \&%f , \ \&%G , \ \&%g
|
||||
Eight byte default, four byte counts supported.
|
||||
.El
|
||||
.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 ``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
|
||||
.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
|
||||
.Nm
|
||||
.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
|
||||
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
|
||||
.Cm \&_a
|
||||
characters or strings unless all but one of the conversion characters or
|
||||
strings is
|
||||
.B \&_a
|
||||
or
|
||||
.Cm \&_A .
|
||||
.Pp
|
||||
.BR \&_A .
|
||||
.PP
|
||||
If, as a result of the specification of the
|
||||
.Fl 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
|
||||
.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
|
||||
.Cm s
|
||||
conversion character with the same field width
|
||||
and precision as the original conversion character or conversion
|
||||
string but with any
|
||||
.Dq Li \&+ ,
|
||||
.Dq \&\ \& ,
|
||||
.Dq Li \&#
|
||||
conversion flag characters
|
||||
removed, and referencing a NULL string.
|
||||
.Pp
|
||||
.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 equivalent
|
||||
to specifying the
|
||||
.Fl x
|
||||
.B \-x
|
||||
option.
|
||||
.Pp
|
||||
.Nm
|
||||
.SH "EXIT STATUS"
|
||||
.B hexdump
|
||||
exits 0 on success and >0 if an error occurred.
|
||||
.Sh EXAMPLES
|
||||
.SH EXAMPLES
|
||||
Display the input in perusal format:
|
||||
.Bd -literal -offset indent
|
||||
"%06.6_ao " 12/1 "%3_u "
|
||||
"\et\et" "%_p "
|
||||
"\en"
|
||||
.Ed
|
||||
.Pp
|
||||
.nf
|
||||
"%06.6_ao " 12/1 "%3_u "
|
||||
"\et\et" "%_p "
|
||||
"\en"
|
||||
.nf
|
||||
.PP
|
||||
Implement the \-x option:
|
||||
.Bd -literal -offset indent
|
||||
"%07.7_Ax\en"
|
||||
"%07.7_ax " 8/2 "%04x " "\en"
|
||||
.Ed
|
||||
.Sh STANDARDS
|
||||
.nf
|
||||
"%07.7_Ax\en"
|
||||
"%07.7_ax " 8/2 "%04x " "\en"
|
||||
.nf
|
||||
.SH STANDARDS
|
||||
The
|
||||
.Nm
|
||||
utility is expected to be
|
||||
.St -p1003.2
|
||||
compatible.
|
||||
.Sh AVAILABILITY
|
||||
.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
|
||||
ftp://ftp.kernel.org/pub/linux/utils/util-linux/.
|
||||
.UR ftp://\:ftp.kernel.org\:/pub\:/linux\:/utils\:/util-linux/
|
||||
Linux Kernel Archive
|
||||
.UE .
|
||||
|
|
|
|||
Loading…
Reference in New Issue