vim

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

xxd.man (12788B)


      1 XXD(1)                      General Commands Manual                     XXD(1)
      2 
      3 NAME
      4        xxd - make a hex dump or do the reverse.
      5 
      6 SYNOPSIS
      7        xxd -h[elp]
      8        xxd [options] [infile [outfile]]
      9        xxd -r[evert] [options] [infile [outfile]]
     10 
     11 DESCRIPTION
     12        xxd  creates a hex dump of a given file or standard input.  It can also
     13        convert a hex dump back to its original binary form.  Like  uuencode(1)
     14        and  uudecode(1)  it allows the transmission of binary data in a `mail-
     15        safe' ASCII representation, but has the advantage of decoding to  stan‐
     16        dard output.  Moreover, it can be used to perform binary file patching.
     17 
     18 OPTIONS
     19        If  no infile is given, standard input is read.  If infile is specified
     20        as a `-' character, then input is taken from  standard  input.   If  no
     21        outfile is given (or a `-' character is in its place), results are sent
     22        to standard output.
     23 
     24        Note  that  a  "lazy" parser is used which does not check for more than
     25        the first option letter, unless the option is followed by a  parameter.
     26        Spaces  between  a single option letter and its parameter are optional.
     27        Parameters to options can be specified in decimal, hexadecimal or octal
     28        notation.  Thus -c8, -c 8, -c 010 and -cols 8 are all equivalent.
     29 
     30        -a | -autoskip
     31               Toggle autoskip: A single '*' replaces NUL-lines.  Default off.
     32 
     33        -b | -bits
     34               Switch to bits (binary digits) dump, rather than hex dump.  This
     35               option writes octets as eight digits "1"s and "0"s instead of  a
     36               normal  hexadecimal dump. Each line is preceded by a line number
     37               in hexadecimal and followed by an ASCII (or EBCDIC)  representa‐
     38               tion.  The  command line switch -p does not work with this mode.
     39               Can be combined with -i.
     40 
     41        -c cols | -cols cols
     42               Format <cols> octets per line. Default 16 (-i: 12, -ps: 30,  -b:
     43               6).  Max  256.   No  maximum for -ps. With -ps, 0 results in one
     44               long line of output.
     45 
     46        -C | -capitalize
     47               Capitalize variable names in C include file  style,  when  using
     48               -i.
     49 
     50        -d     show offset in decimal instead of hex.
     51 
     52        -E | -EBCDIC
     53               Change the character encoding in the righthand column from ASCII
     54               to EBCDIC.  This does not change the hexadecimal representation.
     55               The option is meaningless in combinations with -r, -p or -i.
     56 
     57        -e     Switch  to  little-endian  hex  dump.   This  option treats byte
     58               groups as words in little-endian byte order.  The default group‐
     59               ing of 4 bytes may be changed using -g.  This  option  only  ap‐
     60               plies to the hex dump, leaving the ASCII (or EBCDIC) representa‐
     61               tion  unchanged.   The  command  line switches -r, -p, -i do not
     62               work with this mode.
     63 
     64        -g bytes | -groupsize bytes
     65               Separate the output of every <bytes> bytes (two  hex  characters
     66               or eight bit digits each) by a whitespace.  Specify -g 0 to sup‐
     67               press grouping.  <Bytes> defaults to 2 in normal mode, 4 in lit‐
     68               tle-endian  mode and 1 in bits mode.  Grouping does not apply to
     69               PostScript or include style.
     70 
     71        -h | -help
     72               Print a summary of available commands and exit.  No hex  dumping
     73               is performed.
     74 
     75        -i | -include
     76               Output  in C include file style. A complete static array defini‐
     77               tion is written (named after the input file), unless  xxd  reads
     78               from stdin. Can be combined with -b.
     79 
     80        -l len | -len len
     81               Stop after writing <len> octets.
     82 
     83        -n name  |  -name name
     84               Override  the variable name output when -i is used. The array is
     85               named name and the length is named name_len.
     86 
     87        -o offset
     88               Add <offset> to the displayed file position.
     89 
     90        -p | -ps | -postscript | -plain
     91               Output in PostScript continuous hex dump style.  Also  known  as
     92               plain hex dump style.
     93 
     94        -r | -revert
     95               Reverse  operation: convert (or patch) hex dump into binary.  If
     96               not writing to stdout, xxd writes into its output  file  without
     97               truncating it. Use the combination -r -p to read plain hexadeci‐
     98               mal dumps without line number information and without a particu‐
     99               lar column layout. Additional whitespace and line breaks are al‐
    100               lowed  anywhere.  Use  the combination -r -b to read a bits dump
    101               instead of a hex dump.
    102 
    103        -R when
    104               In the output both the data column (hex, or bits  with  -b)  and
    105               the  character  column are colored with the same color depending
    106               on the byte value. Mostly helping to differentiate printable and
    107               non-printable characters.  when is never, always, or  auto  (de‐
    108               fault:  auto).   When the $NO_COLOR environment variable is set,
    109               colorization will be disabled.
    110 
    111        -seek offset
    112               When used after -r: revert with <offset> added to file positions
    113               found in hex dump.
    114 
    115        -s [+][-]seek
    116               Start at <seek> bytes abs. (or rel.) infile offset.  + indicates
    117               that the seek is relative to the  current  stdin  file  position
    118               (meaningless when not reading from stdin).  - indicates that the
    119               seek  should  be  that many characters from the end of the input
    120               (or if combined with +: before the current stdin file position).
    121               Without -s option, xxd starts at the current file position.
    122 
    123        -t     When outputting in C include file style  using  -i  include  the
    124               terminating zero.
    125 
    126        -u     Use upper-case hex letters. Default is lower-case.
    127 
    128        -v | -version
    129               Show version string.
    130 
    131 CAVEATS
    132        xxd  -r  has  some built-in magic while evaluating line number informa‐
    133        tion.  If the output file is seekable, then the  line  numbers  at  the
    134        start  of each hex dump line may be out of order, lines may be missing,
    135        or overlapping. In these cases xxd will lseek(2) to the next  position.
    136        If  the  output file is not seekable, only gaps are allowed, which will
    137        be filled by null-bytes.
    138 
    139        xxd -r never generates parse errors. Garbage is silently skipped.
    140 
    141        When editing hex dumps, please note that xxd -r skips everything on the
    142        input line after reading enough columns of hexadecimal data (see option
    143        -c). This also means that changes to the printable  ASCII  (or  EBCDIC)
    144        columns are always ignored. Reverting a plain (or PostScript) style hex
    145        dump  with  xxd -r -p does not depend on the correct number of columns.
    146        Here, anything that looks like a pair of hex digits is interpreted.
    147 
    148        Note the difference between
    149        % xxd -i file
    150        and
    151        % xxd -i < file
    152 
    153        xxd -s +seek may be different from xxd -s seek, as lseek(2) is used  to
    154        "rewind" input.  A '+' makes a difference if the input source is stdin,
    155        and  if  stdin's  file  position is not at the start of the file by the
    156        time xxd is started and given its input.  The  following  examples  may
    157        help to clarify (or further confuse!):
    158 
    159        Rewind  stdin before reading; needed because the `cat' has already read
    160        to the end of stdin.
    161        % sh -c "cat > plain_copy; xxd -s 0 > hex_copy" < file
    162 
    163        Hex dump from file position 0x480 (=1024+128) onwards.   The  `+'  sign
    164        means "relative to the current position", thus the `128' adds to the 1k
    165        where dd left off.
    166        %  sh -c "dd of=plain_snippet bs=1k count=1; xxd -s +128 > hex_snippet"
    167        < file
    168 
    169        Hex dump from file position 0x100 (=1024-768) onwards.
    170        % sh -c "dd of=plain_snippet bs=1k count=1; xxd -s +-768 > hex_snippet"
    171        < file
    172 
    173        However, this is a rare situation and the use of `+' is rarely  needed.
    174        The  author  prefers  to  monitor  the  effect of xxd with strace(1) or
    175        truss(1), whenever -s is used.
    176 
    177 EXAMPLES
    178        Print everything but the first three lines (hex 0x30 bytes) of file.
    179        % xxd -s 0x30 file
    180 
    181        Print 3 lines (hex 0x30 bytes) from the end of file.
    182        % xxd -s -0x30 file
    183 
    184        Note: The results of the examples below are relevant to the  xxd.1  man
    185        page as of March 2026
    186 
    187        Print 120 bytes as a continuous hex dump with 20 octets per line.
    188        % xxd -l 120 -ps -c 20 xxd.1
    189        2e544820585844203120224d6172203230323622
    190        20224d616e75616c207061676520666f72207878
    191        64220a2e5c220a2e5c222032317374204d617920
    192        313939360a2e5c22204d616e2070616765206175
    193        74686f723a0a2e5c2220202020546f6e79204e75
    194        67656e74203c746f6e79407363746e7567656e2e
    195 
    196        Hex dump the first 120 bytes of this man page with 12 octets per line.
    197        % xxd -l 120 -c 12 xxd.1
    198        00000000: 2e54 4820 5858 4420 3120 224d  .TH XXD 1 "M
    199        0000000c: 6172 2032 3032 3622 2022 4d61  ar 2026" "Ma
    200        00000018: 6e75 616c 2070 6167 6520 666f  nual page fo
    201        00000024: 7220 7878 6422 0a2e 5c22 0a2e  r xxd"..\"..
    202        00000030: 5c22 2032 3173 7420 4d61 7920  \" 21st May
    203        0000003c: 3139 3936 0a2e 5c22 204d 616e  1996..\" Man
    204        00000048: 2070 6167 6520 6175 7468 6f72   page author
    205        00000054: 3a0a 2e5c 2220 2020 2054 6f6e  :..\"    Ton
    206        00000060: 7920 4e75 6765 6e74 203c 746f  y Nugent <to
    207        0000006c: 6e79 4073 6374 6e75 6765 6e2e  ny@sctnugen.
    208 
    209        Display just the date from the file xxd.1
    210        % xxd -s 0x33 -l 13 -c 13 xxd.1
    211        00000033: 3231 7374 204d 6179 2031 3939 36  21st May 1996
    212 
    213        Copy input_file to output_file and prepend 100 bytes of value 0x00.
    214        % xxd input_file | xxd -r -s 100 > output_file
    215 
    216        Patch the date in the file xxd.1
    217        % echo "0000034: 3574 68" | xxd -r - xxd.1
    218        % xxd -s 0x33 -l 13 -c 13 xxd.1
    219        00000033: 3235 7468 204d 6179 2031 3939 36  25th May 1996
    220 
    221        Create  a  65537 byte file with all bytes 0x00, except for the last one
    222        which is 'A' (hex 0x41).
    223        % echo "010000: 41" | xxd -r > file
    224 
    225        Hex dump this file with autoskip.
    226        % xxd -a -c 12 file
    227        00000000: 0000 0000 0000 0000 0000 0000  ............
    228        *
    229        0000fffc: 0000 0000 41                   ....A
    230 
    231        Create a 1 byte file containing a single 'A' character.  The number af‐
    232        ter '-r -s' adds to the line numbers found in the file; in effect,  the
    233        leading bytes are suppressed.
    234        % echo "010000: 41" | xxd -r -s -0x10000 > file
    235 
    236        Use  xxd  as a filter within an editor such as vim(1) to hex dump a re‐
    237        gion marked between `a' and `z'.
    238        :'a,'z!xxd
    239 
    240        Use xxd as a filter within an editor such as vim(1) to recover a binary
    241        hex dump marked between `a' and `z'.
    242        :'a,'z!xxd -r
    243 
    244        Use xxd as a filter within an editor such as vim(1) to recover one line
    245        of a hex dump.  Move the cursor over the line and type:
    246        !!xxd -r
    247 
    248        Read single characters from a serial line
    249        % xxd -c1 < /dev/term/b &
    250        % stty < /dev/term/b -echo -opost -isig -icanon min 1
    251        % echo -n foo > /dev/term/b
    252 
    253        Output in C style include output with terminating zero
    254        % echo -n "0123456789" > digits
    255        % xxd -i -t digits
    256        unsigned char digits[] = {
    257          0x30, 0x31, 0x32, 0x33, 0x34, 0x35, 0x36, 0x37, 0x38, 0x39, 0x00
    258        };
    259        unsigned int digits_len = 10;
    260 
    261 RETURN VALUES
    262        The following error values are returned:
    263 
    264        0      no errors encountered.
    265 
    266        -1     operation not supported (xxd -r -i still impossible).
    267 
    268        1      error while parsing options.
    269 
    270        2      problems with input file.
    271 
    272        3      problems with output file.
    273 
    274        4,5    desired seek position is unreachable.
    275 
    276 SEE ALSO
    277        uuencode(1), uudecode(1), patch(1)
    278 
    279 WARNINGS
    280        The tool's weirdness matches its creator's brain.  Use entirely at your
    281        own risk. Copy files. Trace it. Become a wizard.
    282 
    283 VERSION
    284        This manual page documents xxd version 1.7 from 2024-05.
    285 
    286 AUTHOR
    287        (c) 1990-1997 by Juergen Weigert
    288        <jnweiger@informatik.uni-erlangen.de>
    289 
    290        Distribute freely and credit me,
    291        make money and share with me,
    292        lose money and don't ask me.
    293 
    294        Manual page started by Tony Nugent
    295        <tony@sctnugen.ppp.gu.edu.au> <T.Nugent@sct.gu.edu.au>
    296        Small changes by Bram Moolenaar.  Edited by Juergen Weigert.
    297 
    298 Manual page for xxd                Mar 2026                             XXD(1)