Mercurial > vim
annotate runtime/doc/xxd.1 @ 20936:c09e47fc4021
Added tag v8.2.1019 for changeset d64520bfafa0cc64f22943beea85be2f7c7a6664
| author | Bram Moolenaar <Bram@vim.org> |
|---|---|
| date | Sat, 20 Jun 2020 14:45:04 +0200 |
| 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 |