Adding upstream version 2.33.1.upstream/2.33.1upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 379 insertions, 0 deletions

diff --git a/text-utils/hexdump.1 b/text-utils/hexdump.1
new file mode 100644
index 0000000..5651a6f
--- /dev/null
+++ b/text-utils/hexdump.1
@@ -0,0 +1,379 @@
+.\" 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 .