diff --git a/text-utils/hexdump.1 b/text-utils/hexdump.1 index ce783c1c5..cbb14fb85 100644 --- a/text-utils/hexdump.1 +++ b/text-utils/hexdump.1 @@ -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 -.It NUL \e0 -.It \ea -.It \eb -.It \ef -.It \en -.It \er -.It \et -.It \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 + +\ea +.TP + +\eb +.TP + +\ef +.TP + +\en +.TP + +\er +.TP + +\et +.TP + +\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 .