xxd.1 (11814B)
1 .TH XXD 1 "Mar 2026" "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 hex dump 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 24 .BR uuencode (1) 25 and 26 .BR uudecode (1) 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 60 Toggle autoskip: A single '*' replaces NUL-lines. Default off. 61 .TP 62 .IR \-b " | " \-bits 63 Switch to bits (binary digits) dump, rather than hex dump. 64 This option writes octets as eight digits "1"s and "0"s instead of a normal 65 hexadecimal dump. Each line is preceded by a line number in hexadecimal and 66 followed by an ASCII (or EBCDIC) representation. The command line switch 67 \-p does not work with this mode. Can be combined with \-i. 68 .TP 69 .IR "\-c cols " | " \-cols cols" 70 Format 71 .RI < cols > 72 octets per line. Default 16 (\-i: 12, \-ps: 30, \-b: 6). Max 256. 73 No maximum for \-ps. With \-ps, 0 results in one long line of output. 74 .TP 75 .IR \-C " | " \-capitalize 76 Capitalize variable names in C include file style, when using \-i. 77 .TP 78 .I \-d 79 show offset in decimal instead of hex. 80 .TP 81 .IR \-E " | " \-EBCDIC 82 Change the character encoding in the righthand column from ASCII to EBCDIC. 83 This does not change the hexadecimal representation. The option is 84 meaningless in combinations with \-r, \-p or \-i. 85 .TP 86 .IR \-e 87 Switch to little-endian hex dump. 88 This option treats byte groups as words in little-endian byte order. 89 The default grouping of 4 bytes may be changed using 90 .RI "" \-g . 91 This option only applies to the hex dump, leaving the ASCII (or EBCDIC) 92 representation unchanged. 93 The command line switches 94 \-r, \-p, \-i do not work with this mode. 95 .TP 96 .IR "\-g bytes " | " \-groupsize bytes" 97 Separate the output of every 98 .RI < bytes > 99 bytes (two hex characters or eight bit digits each) by a whitespace. 100 Specify 101 .I \-g 0 102 to suppress grouping. 103 .RI < Bytes "> defaults to " 2 104 in normal mode, \fI4\fP in little-endian mode and \fI1\fP in bits mode. 105 Grouping does not apply to PostScript or include style. 106 .TP 107 .IR \-h " | " \-help 108 Print a summary of available commands and exit. No hex dumping is performed. 109 .TP 110 .IR \-i " | " \-include 111 Output in C include file style. A complete static array definition is written 112 (named after the input file), unless xxd reads from stdin. Can be combined 113 with \-b. 114 .TP 115 .IR "\-l len " | " \-len len" 116 Stop after writing 117 .RI < len > 118 octets. 119 .TP 120 .I "\-n name " | " \-name name" 121 Override the variable name output when \-i is used. The array is named 122 \fIname\fP and the length is named \fIname\fP_len. 123 .TP 124 .I \-o offset 125 Add 126 .RI < offset > 127 to the displayed file position. 128 .TP 129 .IR \-p " | " \-ps " | " \-postscript " | " \-plain 130 Output in PostScript continuous hex dump style. Also known as plain hex dump 131 style. 132 .TP 133 .IR \-r " | " \-revert 134 Reverse operation: convert (or patch) hex dump into binary. 135 If not writing to stdout, xxd writes into its output file without truncating 136 it. Use the combination 137 .I \-r \-p 138 to read plain hexadecimal dumps without line number information and without a 139 particular column layout. Additional whitespace and line breaks are allowed 140 anywhere. Use the combination 141 .I \-r \-b 142 to read a bits dump instead of a hex dump. 143 .TP 144 .IR \-R " " when 145 In the output both the data column (hex, or bits with \-b) and the character 146 column are colored with the same color depending on the byte value. Mostly 147 helping to differentiate printable and non-printable characters. 148 .I \fIwhen\fP 149 is 150 .BR never ", " always ", or " auto " (default: auto). 151 When the 152 .BR $NO_COLOR 153 environment variable is set, colorization will be disabled. 154 .TP 155 .I \-seek offset 156 When used after 157 .IR \-r : 158 revert with 159 .RI < offset > 160 added to file positions found in hex dump. 161 .TP 162 .I \-s [+][\-]seek 163 Start at 164 .RI < seek > 165 bytes abs. (or rel.) infile offset. 166 \fI+ \fRindicates that the seek is relative to the current stdin file position 167 (meaningless when not reading from stdin). \fI\- \fRindicates that the seek 168 should be that many characters from the end of the input (or if combined with 169 \fI+\fR: before the current stdin file position). 170 Without \-s option, xxd starts at the current file position. 171 .TP 172 .I \-t 173 When outputting in C include file style using \-i include the terminating zero. 174 .TP 175 .I \-u 176 Use upper-case hex letters. Default is lower-case. 177 .TP 178 .IR \-v " | " \-version 179 Show version string. 180 .SH CAVEATS 181 .PP 182 .I xxd \-r 183 has some built-in magic while evaluating line number information. 184 If the output file is seekable, then the line numbers at the start of each 185 hex dump line may be out of order, lines may be missing, or overlapping. In 186 these cases xxd will lseek(2) to the next position. If the output file is not 187 seekable, only gaps are allowed, which will be filled by null-bytes. 188 .PP 189 .I xxd \-r 190 never generates parse errors. Garbage is silently skipped. 191 .PP 192 When editing hex dumps, please note that 193 .I xxd \-r 194 skips everything on the input line after reading enough columns of hexadecimal 195 data (see option \-c). This also means that changes to the printable ASCII (or 196 EBCDIC) columns are always ignored. Reverting a plain (or PostScript) style 197 hex dump with xxd \-r \-p does not depend on the correct number of columns. 198 Here, anything that looks like a pair of hex digits is interpreted. 199 .PP 200 Note the difference between 201 .br 202 \fI% xxd \-i file\fR 203 .br 204 and 205 .br 206 \fI% xxd \-i < file\fR 207 .PP 208 .I xxd \-s +seek 209 may be different from 210 .IR "xxd \-s seek" , 211 as lseek(2) is used to "rewind" input. A '+' 212 makes a difference if the input source is stdin, and if stdin's file position 213 is not at the start of the file by the time xxd is started and given its input. 214 The following examples may help to clarify (or further confuse!): 215 .PP 216 Rewind stdin before reading; needed because the `cat' has already read to the 217 end of stdin. 218 .br 219 \fI% sh \-c "cat > plain_copy; xxd \-s 0 > hex_copy" < file\fR 220 .PP 221 Hex dump from file position 0x480 (=1024+128) onwards. 222 The `+' sign means "relative to the current position", thus the `128' adds to 223 the 1k where dd left off. 224 .br 225 \fI% sh \-c "dd of=plain_snippet bs=1k count=1; xxd \-s +128 > hex_snippet" < file\fR 226 .PP 227 Hex dump from file position 0x100 (=1024\-768) onwards. 228 .br 229 \fI% sh \-c "dd of=plain_snippet bs=1k count=1; xxd \-s +\-768 > hex_snippet" < file\fR 230 .PP 231 However, this is a rare situation and the use of `+' is rarely needed. 232 The author prefers to monitor the effect of xxd with strace(1) or truss(1), 233 whenever \-s is used. 234 .SH EXAMPLES 235 .PP 236 .br 237 Print everything but the first three lines (hex 0x30 bytes) of 238 .BR file . 239 .br 240 \fI% xxd \-s 0x30 file\fR 241 .PP 242 .br 243 Print 3 lines (hex 0x30 bytes) from the end of 244 .BR file . 245 .br 246 \fI% xxd \-s \-0x30 file\fR 247 .PP 248 Note: The results of the examples below are relevant to the xxd.1 man page as of 249 March 2026 250 .PP 251 .br 252 Print 120 bytes as a continuous hex dump with 20 octets per line. 253 .br 254 \fI% xxd \-l 120 \-ps \-c 20 xxd.1\fR 255 .br 256 2e544820585844203120224d6172203230323622 257 .br 258 20224d616e75616c207061676520666f72207878 259 .br 260 64220a2e5c220a2e5c222032317374204d617920 261 .br 262 313939360a2e5c22204d616e2070616765206175 263 .br 264 74686f723a0a2e5c2220202020546f6e79204e75 265 .br 266 67656e74203c746f6e79407363746e7567656e2e 267 .br 268 269 .br 270 Hex dump the first 120 bytes of this man page with 12 octets per line. 271 .br 272 \fI% xxd \-l 120 \-c 12 xxd.1\fR 273 .br 274 00000000: 2e54 4820 5858 4420 3120 224d .TH XXD 1 "M 275 .br 276 0000000c: 6172 2032 3032 3622 2022 4d61 ar 2026" "Ma 277 .br 278 00000018: 6e75 616c 2070 6167 6520 666f nual page fo 279 .br 280 00000024: 7220 7878 6422 0a2e 5c22 0a2e r xxd"..\\".. 281 .br 282 00000030: 5c22 2032 3173 7420 4d61 7920 \\" 21st May 283 .br 284 0000003c: 3139 3936 0a2e 5c22 204d 616e 1996..\\" Man 285 .br 286 00000048: 2070 6167 6520 6175 7468 6f72 page author 287 .br 288 00000054: 3a0a 2e5c 2220 2020 2054 6f6e :..\\" Ton 289 .br 290 00000060: 7920 4e75 6765 6e74 203c 746f y Nugent <to 291 .br 292 0000006c: 6e79 4073 6374 6e75 6765 6e2e ny@sctnugen. 293 .PP 294 .br 295 Display just the date from the file xxd.1 296 .br 297 \fI% xxd \-s 0x33 \-l 13 \-c 13 xxd.1\fR 298 .br 299 00000033: 3231 7374 204d 6179 2031 3939 36 21st May 1996 300 .PP 301 .br 302 Copy 303 .B input_file 304 to 305 .B output_file 306 and prepend 100 bytes of value 0x00. 307 .br 308 \fI% xxd input_file | xxd \-r \-s 100 > output_file\fR 309 .br 310 311 .br 312 Patch the date in the file xxd.1 313 .br 314 \fI% echo "0000034: 3574 68" | xxd \-r \- xxd.1\fR 315 .br 316 \fI% xxd \-s 0x33 \-l 13 \-c 13 xxd.1\fR 317 .br 318 00000033: 3235 7468 204d 6179 2031 3939 36 25th May 1996 319 .PP 320 .br 321 Create a 65537 byte file with all bytes 0x00, 322 except for the last one which is 'A' (hex 0x41). 323 .br 324 \fI% echo "010000: 41" | xxd \-r > file\fR 325 .PP 326 .br 327 Hex dump this file with autoskip. 328 .br 329 \fI% xxd \-a \-c 12 file\fR 330 .br 331 00000000: 0000 0000 0000 0000 0000 0000 ............ 332 .br 333 * 334 .br 335 0000fffc: 0000 0000 41 ....A 336 .PP 337 Create a 1 byte file containing a single 'A' character. 338 The number after '\-r \-s' adds to the line numbers found in the file; 339 in effect, the leading bytes are suppressed. 340 .br 341 \fI% echo "010000: 41" | xxd \-r \-s \-0x10000 > file\fR 342 .PP 343 Use xxd as a filter within an editor such as 344 .B vim(1) 345 to hex dump a region marked between `a' and `z'. 346 .br 347 \fI:'a,'z!xxd\fR 348 .PP 349 Use xxd as a filter within an editor such as 350 .B vim(1) 351 to recover a binary hex dump marked between `a' and `z'. 352 .br 353 \fI:'a,'z!xxd \-r\fR 354 .PP 355 Use xxd as a filter within an editor such as 356 .B vim(1) 357 to recover one line of a hex dump. Move the cursor over the line and type: 358 .br 359 \fI!!xxd \-r\fR 360 .PP 361 Read single characters from a serial line 362 .br 363 \fI% xxd \-c1 < /dev/term/b &\fR 364 .br 365 \fI% stty < /dev/term/b \-echo \-opost \-isig \-icanon min 1\fR 366 .br 367 \fI% echo \-n foo > /dev/term/b\fR 368 .PP 369 Output in C style include output with terminating zero 370 .br 371 \fI% echo -n \&"0123456789\&" > digits\fR 372 .br 373 \fI% xxd -i -t digits\fR 374 .br 375 unsigned char digits[] = { 376 .br 377 0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x00 378 .br 379 }; 380 .br 381 unsigned int digits_len = 10; 382 .PP 383 .SH "RETURN VALUES" 384 The following error values are returned: 385 .TP 386 0 387 no errors encountered. 388 .TP 389 \-1 390 operation not supported 391 \%(\c 392 .I \%xxd \-r \-i 393 still impossible). 394 .TP 395 1 396 error while parsing options. 397 .TP 398 2 399 problems with input file. 400 .TP 401 3 402 problems with output file. 403 .TP 404 4,5 405 desired seek position is unreachable. 406 .SH "SEE ALSO" 407 uuencode(1), uudecode(1), patch(1) 408 .br 409 .SH WARNINGS 410 The tool's weirdness matches its creator's brain. 411 Use entirely at your own risk. Copy files. Trace it. Become a wizard. 412 .br 413 .SH VERSION 414 This manual page documents xxd version 1.7 from 2024-05. 415 .SH AUTHOR 416 .br 417 (c) 1990-1997 by Juergen Weigert 418 .br 419 <jnweiger@informatik.uni\-erlangen.de> 420 .LP 421 Distribute freely and credit me, 422 .br 423 make money and share with me, 424 .br 425 lose money and don't ask me. 426 .PP 427 Manual page started by Tony Nugent 428 .br 429 <tony@sctnugen.ppp.gu.edu.au> <T.Nugent@sct.gu.edu.au> 430 .br 431 Small changes by Bram Moolenaar. 432 Edited by Juergen Weigert. 433 .PP