vim

Fork of vim, an acceptable text editor
git clone git://git.laack.co/vim.git
Log | Files | Refs | README | LICENSE

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