Skip to content

Commit

Permalink
runtime(doc): regenerate xxd manpage
Browse files Browse the repository at this point in the history 
Commit f6fc255 (v9.0.1834) updated xxd.1 but the xxd.man
page wasn't re-generated. So let's just regenerate it now.

Signed-off-by: Christian Brabandt <[email protected]>
  • Loading branch information
@chrisbra
chrisbra committed Sep 27, 2023
1 parent 9eb1ce5 commit e845b38
Showing 1 changed file with 64 additions and 58 deletions.
122 changes: 64 additions & 58 deletions runtime/doc/xxd.man
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ XXD(1) General Commands Manual XXD(1)


NAME
xxd - make a hexdump or do the reverse.
xxd - make a hex dump or do the reverse.

SYNOPSIS
xxd -h[elp]
Expand All @@ -30,19 +30,19 @@ OPTIONS
notation. Thus -c8, -c 8, -c 010 and -cols 8 are all equivalent.

-a | -autoskip
Toggle autoskip: A single '*' replaces nul-lines. Default off.
Toggle autoskip: A single '*' replaces NUL-lines. Default off.

-b | -bits
Switch to bits (binary digits) dump, rather than hexdump. This
Switch to bits (binary digits) dump, rather than hex dump. This
option writes octets as eight digits "1"s and "0"s instead of a
normal hexadecimal dump. Each line is preceded by a line number
in hexadecimal and followed by an ascii (or ebcdic) representa‐
in hexadecimal and followed by an ASCII (or EBCDIC) representa‐
tion. The command line switches -r, -p, -i do not work with this
mode.

-c cols | -cols cols
Format <cols> octets per line. Default 16 (-i: 12, -ps: 30, -b:
6). Max 256. No maxmimum for -ps. With -ps, 0 results in one
6). Max 256. No maximum for -ps. With -ps, 0 results in one
long line of output.

-C | -capitalize
Expand All @@ -54,53 +54,60 @@ OPTIONS
to EBCDIC. This does not change the hexadecimal representation.
The option is meaningless in combinations with -r, -p or -i.

-e Switch to little-endian hexdump. This option treats byte groups
as words in little-endian byte order. The default grouping of 4
bytes may be changed using -g. This option only applies to hex‐
dump, leaving the ASCII (or EBCDIC) representation unchanged.
The command line switches -r, -p, -i do not work with this mode.
-e Switch to little-endian hex dump. This option treats byte
groups as words in little-endian byte order. The default group‐
ing of 4 bytes may be changed using -g. This option only ap‐
plies to the hex dump, leaving the ASCII (or EBCDIC) representa‐
tion unchanged. The command line switches -r, -p, -i do not
work with this mode.

-g bytes | -groupsize bytes
Separate the output of every <bytes> bytes (two hex characters
or eight bit-digits each) by a whitespace. Specify -g 0 to sup‐
Separate the output of every <bytes> bytes (two hex characters
or eight bit digits each) by a whitespace. Specify -g 0 to sup‐
press grouping. <Bytes> defaults to 2 in normal mode, 4 in lit‐
tle-endian mode and 1 in bits mode. Grouping does not apply to
postscript or include style.
tle-endian mode and 1 in bits mode. Grouping does not apply to
PostScript or include style.

-h | -help
Print a summary of available commands and exit. No hex dumping
Print a summary of available commands and exit. No hex dumping
is performed.

-i | -include
Output in C include file style. A complete static array defini‐
tion is written (named after the input file), unless xxd reads
Output in C include file style. A complete static array defini‐
tion is written (named after the input file), unless xxd reads
from stdin.

-l len | -len len
Stop after writing <len> octets.

-n name | -name name
Override the variable name output when -i is used. The array is
Override the variable name output when -i is used. The array is
named name and the length is named name_len.

-o offset
Add <offset> to the displayed file position.

-p | -ps | -postscript | -plain
Output in postscript continuous hexdump style. Also known as
plain hexdump style.
Output in PostScript continuous hex dump style. Also known as
plain hex dump style.

-r | -revert
Reverse operation: convert (or patch) hexdump into binary. If
not writing to stdout, xxd writes into its output file without
Reverse operation: convert (or patch) hex dump into binary. If
not writing to stdout, xxd writes into its output file without
truncating it. Use the combination -r -p to read plain hexadeci‐
mal dumps without line number information and without a particu‐
lar column layout. Additional Whitespace and line-breaks are al‐
lar column layout. Additional whitespace and line breaks are al‐
lowed anywhere.

-R when
In output the hex-value and the value are both colored with the
same color depending on the hex-value. Mostly helping to differ‐
entiate printable and non-printable characters. when is never,
always, or auto.

-seek offset
When used after -r: revert with <offset> added to file positions
found in hexdump.
found in hex dump.

-s [+][-]seek
Start at <seek> bytes abs. (or rel.) infile offset. + indicates
Expand All @@ -110,56 +117,55 @@ OPTIONS
(or if combined with +: before the current stdin file position).
Without -s option, xxd starts at the current file position.

-u Use upper case hex letters. Default is lower case.
-u Use upper-case hex letters. Default is lower-case.

-v | -version
Show version string.

CAVEATS
xxd -r has some builtin magic while evaluating line number information.
If the output file is seekable, then the linenumbers at the start of
each hexdump line may be out of order, lines may be missing, or over‐
lapping. In these cases xxd will lseek(2) to the next position. If the
output file is not seekable, only gaps are allowed, which will be
filled by null-bytes.
xxd -r has some built-in magic while evaluating line number informa‐
tion. If the output file is seekable, then the line numbers at the
start of each hex dump line may be out of order, lines may be missing,
or overlapping. In these cases xxd will lseek(2) to the next position.
If the output file is not seekable, only gaps are allowed, which will
be filled by null-bytes.

xxd -r never generates parse errors. Garbage is silently skipped.

When editing hexdumps, please note that xxd -r skips everything on the
When editing hex dumps, please note that xxd -r skips everything on the
input line after reading enough columns of hexadecimal data (see option
-c). This also means, that changes to the printable ascii (or ebcdic)
columns are always ignored. Reverting a plain (or postscript) style
hexdump with xxd -r -p does not depend on the correct number of col‐
umns. Here anything that looks like a pair of hex-digits is inter‐
preted.
-c). This also means that changes to the printable ASCII (or EBCDIC)
columns are always ignored. Reverting a plain (or PostScript) style hex
dump with xxd -r -p does not depend on the correct number of columns.
Here, anything that looks like a pair of hex digits is interpreted.

Note the difference between
% xxd -i file
and
% xxd -i < file

xxd -s +seek may be different from xxd -s seek, as lseek(2) is used to
xxd -s +seek may be different from xxd -s seek, as lseek(2) is used to
"rewind" input. A '+' makes a difference if the input source is stdin,
and if stdin's file position is not at the start of the file by the
time xxd is started and given its input. The following examples may
help to clarify (or further confuse!)...
and if stdin's file position is not at the start of the file by the
time xxd is started and given its input. The following examples may
help to clarify (or further confuse!):

Rewind stdin before reading; needed because the `cat' has already read
Rewind stdin before reading; needed because the `cat' has already read
to the end of stdin.
% sh -c "cat > plain_copy; xxd -s 0 > hex_copy" < file

Hexdump from file position 0x480 (=1024+128) onwards. The `+' sign
Hex dump from file position 0x480 (=1024+128) onwards. The `+' sign
means "relative to the current position", thus the `128' adds to the 1k
where dd left off.
% sh -c "dd of=plain_snippet bs=1k count=1; xxd -s +128 > hex_snippet"
% sh -c "dd of=plain_snippet bs=1k count=1; xxd -s +128 > hex_snippet"
< file

Hexdump from file position 0x100 ( = 1024-768) on.
Hex dump from file position 0x100 (=1024-768) onwards.
% sh -c "dd of=plain_snippet bs=1k count=1; xxd -s +-768 > hex_snippet"
< file

However, this is a rare situation and the use of `+' is rarely needed.
The author prefers to monitor the effect of xxd with strace(1) or
However, this is a rare situation and the use of `+' is rarely needed.
The author prefers to monitor the effect of xxd with strace(1) or
truss(1), whenever -s is used.

EXAMPLES
Expand All @@ -169,7 +175,7 @@ EXAMPLES
Print 3 lines (hex 0x30 bytes) from the end of file.
% xxd -s -0x30 file

Print 120 bytes as continuous hexdump with 20 octets per line.
Print 120 bytes as a continuous hex dump with 20 octets per line.
% xxd -l 120 -ps -c 20 xxd.1
2e54482058584420312022417567757374203139
39362220224d616e75616c207061676520666f72
Expand All @@ -178,7 +184,7 @@ EXAMPLES
20617574686f723a0a2e5c2220202020546f6e79
204e7567656e74203c746f6e79407363746e7567

Hexdump the first 120 bytes of this man page with 12 octets per line.
Hex dump the first 120 bytes of this man page with 12 octets per line.
% xxd -l 120 -c 12 xxd.1
0000000: 2e54 4820 5858 4420 3120 2241 .TH XXD 1 "A
000000c: 7567 7573 7420 3139 3936 2220 ugust 1996"
Expand All @@ -203,31 +209,31 @@ EXAMPLES
% xxd -s 0x36 -l 13 -c 13 xxd.1
0000036: 3235 7468 204d 6179 2031 3939 36 25th May 1996

Create a 65537 byte file with all bytes 0x00, except for the last one
Create a 65537 byte file with all bytes 0x00, except for the last one
which is 'A' (hex 0x41).
% echo "010000: 41" | xxd -r > file

Hexdump this file with autoskip.
Hex dump this file with autoskip.
% xxd -a -c 12 file
0000000: 0000 0000 0000 0000 0000 0000 ............
*
000fffc: 0000 0000 40 ....A

Create a 1 byte file containing a single 'A' character. The number af‐
ter '-r -s' adds to the linenumbers found in the file; in effect, the
ter '-r -s' adds to the line numbers found in the file; in effect, the
leading bytes are suppressed.
% echo "010000: 41" | xxd -r -s -0x10000 > file

Use xxd as a filter within an editor such as vim(1) to hexdump a region
marked between `a' and `z'.
Use xxd as a filter within an editor such as vim(1) to hex dump a re‐
gion marked between `a' and `z'.
:'a,'z!xxd

Use xxd as a filter within an editor such as vim(1) to recover a binary
hexdump marked between `a' and `z'.
hex dump marked between `a' and `z'.
:'a,'z!xxd -r

Use xxd as a filter within an editor such as vim(1) to recover one line
of a hexdump. Move the cursor over the line and type:
of a hex dump. Move the cursor over the line and type:
!!xxd -r

Read single characters from a serial line
Expand All @@ -240,7 +246,7 @@ RETURN VALUES

0 no errors encountered.

-1 operation not supported ( xxd -r -i still impossible).
-1 operation not supported (xxd -r -i still impossible).

1 error while parsing options.

Expand All @@ -254,7 +260,7 @@ SEE ALSO
uuencode(1), uudecode(1), patch(1)

WARNINGS
The tools weirdness matches its creators brain. Use entirely at your
The tool's weirdness matches its creator's brain. Use entirely at your
own risk. Copy files. Trace it. Become a wizard.

VERSION
Expand Down

0 comments on commit e845b38

Please sign in to comment.