0
0
mirror of https://github.com/vim/vim.git synced 2025-07-04 23:07:33 -04:00
vim/runtime/doc/xxd.man

263 lines
10 KiB
Groff
Raw Normal View History

2004-12-09 21:34:53 +00:00
XXD(1) XXD(1)
2004-06-13 20:20:40 +00:00
NAME
xxd - make a hexdump or do the reverse.
SYNOPSIS
xxd -h[elp]
xxd [options] [infile [outfile]]
xxd -r[evert] [options] [infile [outfile]]
DESCRIPTION
2004-12-09 21:34:53 +00:00
xxd creates a hex dump of a given file or standard input. It can also
convert a hex dump back to its original binary form. Like uuencode(1)
and uudecode(1) it allows the transmission of binary data in a `mail-
safe' ASCII representation, but has the advantage of decoding to stan-
dard output. Moreover, it can be used to perform binary file patching.
2004-06-13 20:20:40 +00:00
OPTIONS
2004-12-09 21:34:53 +00:00
If no infile is given, standard input is read. If infile is specified
as a `-' character, then input is taken from standard input. If no
outfile is given (or a `-' character is in its place), results are sent
to standard output.
2004-06-13 20:20:40 +00:00
2004-12-09 21:34:53 +00:00
Note that a "lazy" parser is used which does not check for more than
the first option letter, unless the option is followed by a parameter.
Spaces between a single option letter and its parameter are optional.
Parameters to options can be specified in decimal, hexadecimal or octal
notation. Thus -c8, -c 8, -c 010 and -cols 8 are all equivalent.
2004-06-13 20:20:40 +00:00
-a | -autoskip
2004-12-09 21:34:53 +00:00
toggle autoskip: A single '*' replaces nul-lines. Default off.
2004-06-13 20:20:40 +00:00
-b | -bits
2004-12-09 21:34:53 +00:00
Switch to bits (binary digits) dump, rather than hexdump. 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-
tion. The command line switches -r, -p, -i do not work with this
mode.
2004-06-13 20:20:40 +00:00
-c cols | -cols cols
2004-12-09 21:34:53 +00:00
format <cols> octets per line. Default 16 (-i: 12, -ps: 30, -b:
6). Max 256.
2004-06-13 20:20:40 +00:00
-E | -EBCDIC
2004-12-09 21:34:53 +00:00
Change the character encoding in the righthand column from ASCII
to EBCDIC. This does not change the hexadecimal representation.
The option is meaningless in combinations with -r, -p or -i.
2004-06-13 20:20:40 +00:00
-g bytes | -groupsize bytes
2004-12-09 21:34:53 +00:00
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 and 1 in
bits mode. Grouping does not apply to postscript or include
2004-06-13 20:20:40 +00:00
style.
-h | -help
2004-12-09 21:34:53 +00:00
print a summary of available commands and exit. No hex dumping
is performed.
2004-06-13 20:20:40 +00:00
-i | -include
2004-12-09 21:34:53 +00:00
output in C include file style. A complete static array defini-
tion is written (named after the input file), unless xxd reads
from stdin.
2004-06-13 20:20:40 +00:00
-l len | -len len
stop after writing <len> octets.
-p | -ps | -postscript | -plain
2004-12-09 21:34:53 +00:00
output in postscript continuous hexdump style. Also known as
plain hexdump style.
2004-06-13 20:20:40 +00:00
-r | -revert
2004-12-09 21:34:53 +00:00
reverse operation: convert (or patch) hexdump 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
allowed anywhere.
2004-06-13 20:20:40 +00:00
-seek offset
2005-03-18 20:30:32 +00:00
When used after -r: revert with <offset> added to file positions
found in hexdump.
2004-06-13 20:20:40 +00:00
-s [+][-]seek
2007-05-05 18:27:07 +00:00
start at <seek> bytes abs. (or rel.) infile offset. + indicates
that the seek is relative to the current stdin file position
(meaningless when not reading from stdin). - indicates that the
seek should be that many characters from the end of the input
(or if combined with +: before the current stdin file position).
Without -s option, xxd starts at the current file position.
2004-12-09 21:34:53 +00:00
-u use upper case hex letters. Default is lower case.
2004-06-13 20:20:40 +00:00
-v | -version
show version string.
CAVEATS
2004-12-09 21:34:53 +00:00
xxd -r has some builtin magic while evaluating line number information.
2007-05-05 18:27:07 +00:00
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
2004-12-09 21:34:53 +00:00
filled by null-bytes.
xxd -r never generates parse errors. Garbage is silently skipped.
2007-05-05 18:27:07 +00:00
When editing hexdumps, please note that xxd -r skips everything on the
2004-12-09 21:34:53 +00:00
input line after reading enough columns of hexadecimal data (see option
2007-05-05 18:27:07 +00:00
-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-
2004-12-09 21:34:53 +00:00
preted.
2004-06-13 20:20:40 +00:00
Note the difference between
% xxd -i file
and
% xxd -i < file
2007-05-05 18:27:07 +00:00
xxd -s +seek may be different from xxd -s seek, as lseek(2) is used to
2004-12-09 21:34:53 +00:00
"rewind" input. A '+' makes a difference if the input source is stdin,
2007-05-05 18:27:07 +00:00
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
2004-12-09 21:34:53 +00:00
help to clarify (or further confuse!)...
2004-06-13 20:20:40 +00:00
2007-05-05 18:27:07 +00:00
Rewind stdin before reading; needed because the `cat' has already read
2004-12-09 21:34:53 +00:00
to the end of stdin.
2006-03-27 17:01:56 +00:00
% sh -c "cat > plain_copy; xxd -s 0 > hex_copy" < file
2004-06-13 20:20:40 +00:00
2007-05-05 18:27:07 +00:00
Hexdump from file position 0x480 (=1024+128) onwards. The `+' sign
2004-12-09 21:34:53 +00:00
means "relative to the current position", thus the `128' adds to the 1k
where dd left off.
2007-05-05 18:27:07 +00:00
% sh -c "dd of=plain_snippet bs=1k count=1; xxd -s +128 > hex_snippet"
2004-12-09 21:34:53 +00:00
< file
2004-06-13 20:20:40 +00:00
Hexdump from file position 0x100 ( = 1024-768) on.
2006-03-27 17:01:56 +00:00
% sh -c "dd of=plain_snippet bs=1k count=1; xxd -s +-768 > hex_snippet"
2004-12-09 21:34:53 +00:00
< file
2004-06-13 20:20:40 +00:00
2007-05-05 18:27:07 +00:00
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
2004-12-09 21:34:53 +00:00
truss(1), whenever -s is used.
2004-06-13 20:20:40 +00:00
EXAMPLES
2006-03-27 17:01:56 +00:00
Print everything but the first three lines (hex 0x30 bytes) of file.
2004-06-13 20:20:40 +00:00
% xxd -s 0x30 file
2006-03-27 17:01:56 +00:00
Print 3 lines (hex 0x30 bytes) from the end of file.
2004-06-13 20:20:40 +00:00
% xxd -s -0x30 file
2007-05-05 18:27:07 +00:00
Print 120 bytes as continuous hexdump with 20 octets per line.
2004-06-13 20:20:40 +00:00
% xxd -l 120 -ps -c 20 xxd.1
2004-12-09 21:34:53 +00:00
2e54482058584420312022417567757374203139
39362220224d616e75616c207061676520666f72
20787864220a2e5c220a2e5c222032317374204d
617920313939360a2e5c22204d616e2070616765
20617574686f723a0a2e5c2220202020546f6e79
204e7567656e74203c746f6e79407363746e7567
Hexdump the first 120 bytes of this man page with 12 octets per line.
2004-06-13 20:20:40 +00:00
% xxd -l 120 -c 12 xxd.1
2004-12-09 21:34:53 +00:00
0000000: 2e54 4820 5858 4420 3120 2241 .TH XXD 1 "A
000000c: 7567 7573 7420 3139 3936 2220 ugust 1996"
0000018: 224d 616e 7561 6c20 7061 6765 "Manual page
0000024: 2066 6f72 2078 7864 220a 2e5c for xxd"..\
0000030: 220a 2e5c 2220 3231 7374 204d "..\" 21st M
000003c: 6179 2031 3939 360a 2e5c 2220 ay 1996..\"
0000048: 4d61 6e20 7061 6765 2061 7574 Man page aut
0000054: 686f 723a 0a2e 5c22 2020 2020 hor:..\"
0000060: 546f 6e79 204e 7567 656e 7420 Tony Nugent
000006c: 3c74 6f6e 7940 7363 746e 7567 <tony@sctnug
2004-06-13 20:20:40 +00:00
Display just the date from the file xxd.1
2004-12-09 21:34:53 +00:00
% xxd -s 0x36 -l 13 -c 13 xxd.1
0000036: 3231 7374 204d 6179 2031 3939 36 21st May 1996
2004-06-13 20:20:40 +00:00
2004-12-09 21:34:53 +00:00
Copy input_file to output_file and prepend 100 bytes of value 0x00.
2004-06-13 20:20:40 +00:00
% xxd input_file | xxd -r -s 100 > output_file
Patch the date in the file xxd.1
2006-03-27 17:01:56 +00:00
% echo "0000037: 3574 68" | xxd -r - xxd.1
2004-12-09 21:34:53 +00:00
% xxd -s 0x36 -l 13 -c 13 xxd.1
0000036: 3235 7468 204d 6179 2031 3939 36 25th May 1996
2004-06-13 20:20:40 +00:00
2007-05-05 18:27:07 +00:00
Create a 65537 byte file with all bytes 0x00, except for the last one
2004-12-09 21:34:53 +00:00
which is 'A' (hex 0x41).
2006-03-27 17:01:56 +00:00
% echo "010000: 41" | xxd -r > file
2004-06-13 20:20:40 +00:00
Hexdump this file with autoskip.
% xxd -a -c 12 file
0000000: 0000 0000 0000 0000 0000 0000 ............
*
000fffc: 0000 0000 40 ....A
2007-05-05 18:27:07 +00:00
Create a 1 byte file containing a single 'A' character. The number
2004-12-09 21:34:53 +00:00
after '-r -s' adds to the linenumbers found in the file; in effect, the
leading bytes are suppressed.
2006-03-27 17:01:56 +00:00
% echo "010000: 41" | xxd -r -s -0x10000 > file
2004-06-13 20:20:40 +00:00
2004-12-09 21:34:53 +00:00
Use xxd as a filter within an editor such as vim(1) to hexdump a region
marked between `a' and `z'.
2004-06-13 20:20:40 +00:00
:'a,'z!xxd
2004-12-09 21:34:53 +00:00
Use xxd as a filter within an editor such as vim(1) to recover a binary
hexdump marked between `a' and `z'.
2004-06-13 20:20:40 +00:00
:'a,'z!xxd -r
2004-12-09 21:34:53 +00:00
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:
2004-06-13 20:20:40 +00:00
!!xxd -r
Read single characters from a serial line
% xxd -c1 < /dev/term/b &
% stty < /dev/term/b -echo -opost -isig -icanon min 1
% echo -n foo > /dev/term/b
RETURN VALUES
The following error values are returned:
0 no errors encountered.
2004-12-09 21:34:53 +00:00
-1 operation not supported ( xxd -r -i still impossible).
2004-06-13 20:20:40 +00:00
1 error while parsing options.
2 problems with input file.
3 problems with output file.
4,5 desired seek position is unreachable.
SEE ALSO
uuencode(1), uudecode(1), patch(1)
WARNINGS
2007-05-05 18:27:07 +00:00
The tools weirdness matches its creators brain. Use entirely at your
2004-12-09 21:34:53 +00:00
own risk. Copy files. Trace it. Become a wizard.
2004-06-13 20:20:40 +00:00
VERSION
This manual page documents xxd version 1.7
AUTHOR
(c) 1990-1997 by Juergen Weigert
<jnweiger@informatik.uni-erlangen.de>
Distribute freely and credit me,
make money and share with me,
lose money and don't ask me.
Manual page started by Tony Nugent
<tony@sctnugen.ppp.gu.edu.au> <T.Nugent@sct.gu.edu.au>
2004-12-09 21:34:53 +00:00
Small changes by Bram Moolenaar. Edited by Juergen Weigert.
2004-06-13 20:20:40 +00:00
2004-12-09 21:34:53 +00:00
Manual page for xxd August 1996 XXD(1)