Mercurial > vim
annotate runtime/doc/xxd.1 @ 19664:ffe105b08a03
Added tag v8.2.0388 for changeset f43c0e669bd65a8d9b1fc4f3ba53f7d4d5aaadc3
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Sun, 15 Mar 2020 18:30:06 +0100 |
parents | 362b27e3f702 |
children | 2f854597399f |
rev | line source |
---|---|
7 | 1 .TH XXD 1 "August 1996" "Manual page for xxd" |
2 .\" | |
3 .\" 21st May 1996 | |
4 .\" Man page author: | |
5 .\" Tony Nugent <tony@sctnugen.ppp.gu.edu.au> <T.Nugent@sct.gu.edu.au> | |
6 .\" Changes by Bram Moolenaar <Bram@vim.org> | |
7 .SH NAME | |
8 .I xxd | |
9 \- make a hexdump or do the reverse. | |
10 .SH SYNOPSIS | |
11 .B xxd | |
12 \-h[elp] | |
13 .br | |
14 .B xxd | |
15 [options] [infile [outfile]] | |
16 .br | |
17 .B xxd | |
18 \-r[evert] [options] [infile [outfile]] | |
19 .SH DESCRIPTION | |
20 .I xxd | |
21 creates a hex dump of a given file or standard input. | |
22 It can also convert a hex dump back to its original binary form. | |
23 Like | |
216 | 24 .BR uuencode (1) |
7 | 25 and |
216 | 26 .BR uudecode (1) |
7 | 27 it allows the transmission of binary data in a `mail-safe' ASCII representation, |
28 but has the advantage of decoding to standard output. | |
29 Moreover, it can be used to perform binary file patching. | |
30 .SH OPTIONS | |
31 If no | |
32 .I infile | |
33 is given, standard input is read. | |
34 If | |
35 .I infile | |
36 is specified as a | |
37 .RB \` \- ' | |
38 character, then input is taken from standard input. | |
39 If no | |
40 .I outfile | |
41 is given (or a | |
42 .RB \` \- ' | |
43 character is in its place), results are sent to standard output. | |
44 .PP | |
45 Note that a "lazy" parser is used which does not check for more than the first | |
46 option letter, unless the option is followed by a parameter. | |
47 Spaces between a single option letter and its parameter are optional. | |
48 Parameters to options can be specified in decimal, hexadecimal or octal | |
49 notation. | |
50 Thus | |
51 .BR \-c8 , | |
52 .BR "\-c 8" , | |
53 .B \-c 010 | |
54 and | |
55 .B \-cols 8 | |
56 are all equivalent. | |
57 .PP | |
58 .TP | |
59 .IR \-a " | " \-autoskip | |
13571
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
60 Toggle autoskip: A single '*' replaces nul-lines. Default off. |
7 | 61 .TP |
62 .IR \-b " | " \-bits | |
63 Switch to bits (binary digits) dump, rather than hexdump. | |
64 This option writes octets as eight digits "1"s and "0"s instead of a normal | |
36 | 65 hexadecimal dump. Each line is preceded by a line number in hexadecimal and |
7 | 66 followed by an ascii (or ebcdic) representation. The command line switches |
67 \-r, \-p, \-i do not work with this mode. | |
68 .TP | |
69 .IR "\-c cols " | " \-cols cols" | |
13571
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
70 Format |
7 | 71 .RI < cols > |
72 octets per line. Default 16 (\-i: 12, \-ps: 30, \-b: 6). Max 256. | |
73 .TP | |
13571
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
74 .IR \-C " | " \-capitalize |
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
75 Capitalize variable names in C include file style, when using \-i. |
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
76 .TP |
7 | 77 .IR \-E " | " \-EBCDIC |
78 Change the character encoding in the righthand column from ASCII to EBCDIC. | |
79 This does not change the hexadecimal representation. The option is | |
80 meaningless in combinations with \-r, \-p or \-i. | |
81 .TP | |
6655 | 82 .IR \-e |
83 Switch to little-endian hexdump. | |
84 This option treats byte groups as words in little-endian byte order. | |
85 The default grouping of 4 bytes may be changed using | |
86 .RI "" \-g . | |
87 This option only applies to hexdump, leaving the ASCII (or EBCDIC) | |
88 representation unchanged. | |
89 The command line switches | |
90 \-r, \-p, \-i do not work with this mode. | |
91 .TP | |
7 | 92 .IR "\-g bytes " | " \-groupsize bytes" |
13571
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
93 Separate the output of every |
7 | 94 .RI < bytes > |
95 bytes (two hex characters or eight bit-digits each) by a whitespace. | |
96 Specify | |
97 .I \-g 0 | |
98 to suppress grouping. | |
99 .RI < Bytes "> defaults to " 2 | |
6655 | 100 in normal mode, \fI4\fP in little-endian mode and \fI1\fP in bits mode. |
7 | 101 Grouping does not apply to postscript or include style. |
102 .TP | |
103 .IR \-h " | " \-help | |
13571
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
104 Print a summary of available commands and exit. No hex dumping is performed. |
7 | 105 .TP |
106 .IR \-i " | " \-include | |
13571
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
107 Output in C include file style. A complete static array definition is written |
7 | 108 (named after the input file), unless xxd reads from stdin. |
109 .TP | |
110 .IR "\-l len " | " \-len len" | |
13571
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
111 Stop after writing |
7 | 112 .RI < len > |
113 octets. | |
114 .TP | |
6655 | 115 .I \-o offset |
13571
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
116 Add |
6655 | 117 .RI < offset > |
118 to the displayed file position. | |
119 .TP | |
7 | 120 .IR \-p " | " \-ps " | " \-postscript " | " \-plain |
13571
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
121 Output in postscript continuous hexdump style. Also known as plain hexdump |
7 | 122 style. |
123 .TP | |
124 .IR \-r " | " \-revert | |
13571
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
125 Reverse operation: convert (or patch) hexdump into binary. |
7 | 126 If not writing to stdout, xxd writes into its output file without truncating |
127 it. Use the combination | |
128 .I \-r \-p | |
129 to read plain hexadecimal dumps without line number information and without a | |
130 particular column layout. Additional Whitespace and line-breaks are allowed | |
131 anywhere. | |
132 .TP | |
133 .I \-seek offset | |
134 When used after | |
216 | 135 .IR \-r : |
136 revert with | |
7 | 137 .RI < offset > |
138 added to file positions found in hexdump. | |
139 .TP | |
216 | 140 .I \-s [+][\-]seek |
13571
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
141 Start at |
7 | 142 .RI < seek > |
143 bytes abs. (or rel.) infile offset. | |
1125 | 144 \fI+ \fRindicates that the seek is relative to the current stdin file position |
7 | 145 (meaningless when not reading from stdin). \fI\- \fRindicates that the seek |
146 should be that many characters from the end of the input (or if combined with | |
216 | 147 \fI+\fR: before the current stdin file position). |
7 | 148 Without \-s option, xxd starts at the current file position. |
149 .TP | |
150 .I \-u | |
13571
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
151 Use upper case hex letters. Default is lower case. |
7 | 152 .TP |
153 .IR \-v " | " \-version | |
13571
362b27e3f702
patch 8.0.1658: capitalize argument not available in long form
Christian Brabandt <cb@256bit.org>
parents:
6655
diff
changeset
|
154 Show version string. |
7 | 155 .SH CAVEATS |
156 .PP | |
157 .I xxd \-r | |
158 has some builtin magic while evaluating line number information. | |
36 | 159 If the output file is seekable, then the linenumbers at the start of each |
7 | 160 hexdump line may be out of order, lines may be missing, or overlapping. In |
161 these cases xxd will lseek(2) to the next position. If the output file is not | |
162 seekable, only gaps are allowed, which will be filled by null-bytes. | |
163 .PP | |
164 .I xxd \-r | |
165 never generates parse errors. Garbage is silently skipped. | |
166 .PP | |
167 When editing hexdumps, please note that | |
168 .I xxd \-r | |
169 skips everything on the input line after reading enough columns of hexadecimal | |
170 data (see option \-c). This also means, that changes to the printable ascii (or | |
171 ebcdic) columns are always ignored. Reverting a plain (or postscript) style | |
36 | 172 hexdump 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. |
7 | 173 .PP |
174 Note the difference between | |
175 .br | |
176 \fI% xxd \-i file\fR | |
177 .br | |
178 and | |
179 .br | |
216 | 180 \fI% xxd \-i < file\fR |
7 | 181 .PP |
810 | 182 .I xxd \-s +seek |
7 | 183 may be different from |
216 | 184 .IR "xxd \-s seek" , |
185 as lseek(2) is used to "rewind" input. A '+' | |
7 | 186 makes a difference if the input source is stdin, and if stdin's file position |
187 is not at the start of the file by the time xxd is started and given its input. | |
188 The following examples may help to clarify (or further confuse!)... | |
189 .PP | |
190 Rewind stdin before reading; needed because the `cat' has already read to the | |
191 end of stdin. | |
192 .br | |
1125 | 193 \fI% sh \-c "cat > plain_copy; xxd \-s 0 > hex_copy" < file\fR |
7 | 194 .PP |
195 Hexdump from file position 0x480 (=1024+128) onwards. | |
196 The `+' sign means "relative to the current position", thus the `128' adds to | |
197 the 1k where dd left off. | |
198 .br | |
1125 | 199 \fI% sh \-c "dd of=plain_snippet bs=1k count=1; xxd \-s +128 > hex_snippet" < file\fR |
7 | 200 .PP |
216 | 201 Hexdump from file position 0x100 ( = 1024\-768) on. |
7 | 202 .br |
1125 | 203 \fI% sh \-c "dd of=plain_snippet bs=1k count=1; xxd \-s +\-768 > hex_snippet" < file\fR |
7 | 204 .PP |
205 However, this is a rare situation and the use of `+' is rarely needed. | |
36 | 206 The author prefers to monitor the effect of xxd with strace(1) or truss(1), whenever \-s is used. |
7 | 207 .SH EXAMPLES |
208 .PP | |
209 .br | |
210 Print everything but the first three lines (hex 0x30 bytes) of | |
810 | 211 .BR file . |
7 | 212 .br |
1125 | 213 \fI% xxd \-s 0x30 file\fR |
7 | 214 .PP |
215 .br | |
216 Print 3 lines (hex 0x30 bytes) from the end of | |
810 | 217 .BR file . |
7 | 218 .br |
1125 | 219 \fI% xxd \-s \-0x30 file\fR |
7 | 220 .PP |
221 .br | |
1125 | 222 Print 120 bytes as continuous hexdump with 20 octets per line. |
7 | 223 .br |
224 \fI% xxd \-l 120 \-ps \-c 20 xxd.1\fR | |
225 .br | |
36 | 226 2e54482058584420312022417567757374203139 |
7 | 227 .br |
36 | 228 39362220224d616e75616c207061676520666f72 |
7 | 229 .br |
36 | 230 20787864220a2e5c220a2e5c222032317374204d |
7 | 231 .br |
36 | 232 617920313939360a2e5c22204d616e2070616765 |
7 | 233 .br |
36 | 234 20617574686f723a0a2e5c2220202020546f6e79 |
7 | 235 .br |
36 | 236 204e7567656e74203c746f6e79407363746e7567 |
7 | 237 .br |
238 | |
239 .br | |
240 Hexdump the first 120 bytes of this man page with 12 octets per line. | |
241 .br | |
242 \fI% xxd \-l 120 \-c 12 xxd.1\fR | |
243 .br | |
36 | 244 0000000: 2e54 4820 5858 4420 3120 2241 .TH XXD 1 "A |
7 | 245 .br |
36 | 246 000000c: 7567 7573 7420 3139 3936 2220 ugust 1996" |
7 | 247 .br |
36 | 248 0000018: 224d 616e 7561 6c20 7061 6765 "Manual page |
7 | 249 .br |
36 | 250 0000024: 2066 6f72 2078 7864 220a 2e5c for xxd"..\\ |
7 | 251 .br |
36 | 252 0000030: 220a 2e5c 2220 3231 7374 204d "..\\" 21st M |
7 | 253 .br |
36 | 254 000003c: 6179 2031 3939 360a 2e5c 2220 ay 1996..\\" |
7 | 255 .br |
36 | 256 0000048: 4d61 6e20 7061 6765 2061 7574 Man page aut |
7 | 257 .br |
36 | 258 0000054: 686f 723a 0a2e 5c22 2020 2020 hor:..\\" |
7 | 259 .br |
36 | 260 0000060: 546f 6e79 204e 7567 656e 7420 Tony Nugent |
7 | 261 .br |
36 | 262 000006c: 3c74 6f6e 7940 7363 746e 7567 <tony@sctnug |
7 | 263 .PP |
264 .br | |
265 Display just the date from the file xxd.1 | |
266 .br | |
36 | 267 \fI% xxd \-s 0x36 \-l 13 \-c 13 xxd.1\fR |
7 | 268 .br |
36 | 269 0000036: 3231 7374 204d 6179 2031 3939 36 21st May 1996 |
7 | 270 .PP |
271 .br | |
272 Copy | |
273 .B input_file | |
274 to | |
275 .B output_file | |
276 and prepend 100 bytes of value 0x00. | |
277 .br | |
810 | 278 \fI% xxd input_file | xxd \-r \-s 100 > output_file\fR |
7 | 279 .br |
280 | |
281 .br | |
282 Patch the date in the file xxd.1 | |
283 .br | |
810 | 284 \fI% echo "0000037: 3574 68" | xxd \-r \- xxd.1\fR |
7 | 285 .br |
36 | 286 \fI% xxd \-s 0x36 \-l 13 \-c 13 xxd.1\fR |
7 | 287 .br |
36 | 288 0000036: 3235 7468 204d 6179 2031 3939 36 25th May 1996 |
7 | 289 .PP |
290 .br | |
291 Create a 65537 byte file with all bytes 0x00, | |
292 except for the last one which is 'A' (hex 0x41). | |
293 .br | |
810 | 294 \fI% echo "010000: 41" | xxd \-r > file\fR |
7 | 295 .PP |
296 .br | |
297 Hexdump this file with autoskip. | |
298 .br | |
299 \fI% xxd \-a \-c 12 file\fR | |
300 .br | |
301 0000000: 0000 0000 0000 0000 0000 0000 ............ | |
302 .br | |
303 * | |
304 .br | |
305 000fffc: 0000 0000 40 ....A | |
306 .PP | |
307 Create a 1 byte file containing a single 'A' character. | |
308 The number after '\-r \-s' adds to the linenumbers found in the file; | |
309 in effect, the leading bytes are suppressed. | |
310 .br | |
810 | 311 \fI% echo "010000: 41" | xxd \-r \-s \-0x10000 > file\fR |
7 | 312 .PP |
313 Use xxd as a filter within an editor such as | |
314 .B vim(1) | |
315 to hexdump a region marked between `a' and `z'. | |
316 .br | |
317 \fI:'a,'z!xxd\fR | |
318 .PP | |
319 Use xxd as a filter within an editor such as | |
320 .B vim(1) | |
321 to recover a binary hexdump marked between `a' and `z'. | |
322 .br | |
323 \fI:'a,'z!xxd \-r\fR | |
324 .PP | |
325 Use xxd as a filter within an editor such as | |
326 .B vim(1) | |
327 to recover one line of a hexdump. Move the cursor over the line and type: | |
328 .br | |
329 \fI!!xxd \-r\fR | |
330 .PP | |
331 Read single characters from a serial line | |
332 .br | |
333 \fI% xxd \-c1 < /dev/term/b &\fR | |
334 .br | |
335 \fI% stty < /dev/term/b \-echo \-opost \-isig \-icanon min 1\fR | |
336 .br | |
337 \fI% echo \-n foo > /dev/term/b\fR | |
338 .PP | |
339 .SH "RETURN VALUES" | |
340 The following error values are returned: | |
341 .TP | |
342 0 | |
343 no errors encountered. | |
344 .TP | |
345 \-1 | |
346 operation not supported ( | |
347 .I xxd \-r \-i | |
348 still impossible). | |
349 .TP | |
350 1 | |
351 error while parsing options. | |
352 .TP | |
353 2 | |
354 problems with input file. | |
355 .TP | |
356 3 | |
357 problems with output file. | |
358 .TP | |
359 4,5 | |
360 desired seek position is unreachable. | |
361 .SH "SEE ALSO" | |
362 uuencode(1), uudecode(1), patch(1) | |
363 .br | |
364 .SH WARNINGS | |
365 The tools weirdness matches its creators brain. | |
366 Use entirely at your own risk. Copy files. Trace it. Become a wizard. | |
367 .br | |
368 .SH VERSION | |
369 This manual page documents xxd version 1.7 | |
370 .SH AUTHOR | |
371 .br | |
372 (c) 1990-1997 by Juergen Weigert | |
373 .br | |
810 | 374 <jnweiger@informatik.uni\-erlangen.de> |
7 | 375 .LP |
376 Distribute freely and credit me, | |
377 .br | |
378 make money and share with me, | |
379 .br | |
380 lose money and don't ask me. | |
381 .PP | |
382 Manual page started by Tony Nugent | |
383 .br | |
384 <tony@sctnugen.ppp.gu.edu.au> <T.Nugent@sct.gu.edu.au> | |
385 .br | |
386 Small changes by Bram Moolenaar. | |
387 Edited by Juergen Weigert. | |
388 .PP |