diff options
Diffstat (limited to 'text-utils/hexdump.1')
| -rw-r--r-- | text-utils/hexdump.1 | 382 |
1 files changed, 382 insertions, 0 deletions
diff --git a/text-utils/hexdump.1 b/text-utils/hexdump.1 new file mode 100644 index 0000000..99b9d06 --- /dev/null +++ b/text-utils/hexdump.1 @@ -0,0 +1,382 @@ +.\" 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. +Invoking the program as +.B hd +implies this option. +.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 +.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 +.RE +.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 CONFORMING TO +The +.B hexdump +utility is expected to be IEEE Std 1003.2 ("POSIX.2") compatible. +.SH EXAMPLES +Display the input in perusal format: +.nf + "%06.6_ao " 12/1 "%3_u " + "\et\et" "%_p " + "\en" +.fi +.PP +Implement the \-x option: +.nf + "%07.7_Ax\en" + "%07.7_ax " 8/2 "%04x " "\en" +.fi +.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" +.fi +.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 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 . |