# Writing Hexdumps
By default **hhh** generates hexdumps. These look much like hexdumps produced by other tools. For example, here is a portion of the hexdump of a "hello world" ELF executable.
```bash
$ hhh test_files/hello | head -10
00000000: 7f 45 4c 46 02 01 01 00 00 00 00 00 00 00 00 00 // .ELF............
00000010: 02 00 3e 00 01 00 00 00 00 10 40 00 00 00 00 00 // ..>.......@.....
00000020: 40 00 00 00 00 00 00 00 40 11 00 00 00 00 00 00 // @.......@.......
00000030: 00 00 00 00 40 00 38 00 02 00 40 00 05 00 04 00 // ....@.8...@.....
00000040: 01 00 00 00 04 00 00 00 00 00 00 00 00 00 00 00 // ................
00000050: 00 00 40 00 00 00 00 00 00 00 40 00 00 00 00 00 // ..@.......@.....
00000060: b0 00 00 00 00 00 00 00 b0 00 00 00 00 00 00 00 // ................
00000070: 00 10 00 00 00 00 00 00 01 00 00 00 05 00 00 00 // ................
00000080: 00 10 00 00 00 00 00 00 00 10 40 00 00 00 00 00 // ..........@.....
00000090: 00 10 40 00 00 00 00 00 30 00 00 00 00 00 00 00 // ..@.....0.......
```
Multiple files can be specified as input, and these are treated as if concatenated. If no files are given, then standard input is read.
Output is written to standard output unless the `-o` or `--output` switch is given to specify an output file.
## Grouping
The above shows the file as single bytes, but you can change this with two options.
- Set the number of bytes per group with `-b` or `--bytes-per-group`, limited to 65,536
- Set the number of groups per line with `-g` or `--groups-per-line`, limited to 65,536
```bash
$ hhh -b8 -g2 test_files/hello | head -10
00000000: 7f454c4602010100 0000000000000000 // .ELF............
00000010: 02003e0001000000 0010400000000000 // ..>.......@.....
00000020: 4000000000000000 4011000000000000 // @.......@.......
00000030: 0000000040003800 0200400005000400 // ....@.8...@.....
00000040: 0100000004000000 0000000000000000 // ................
00000050: 0000400000000000 0000400000000000 // ..@.......@.....
00000060: b000000000000000 b000000000000000 // ................
00000070: 0010000000000000 0100000005000000 // ................
00000080: 0010000000000000 0010400000000000 // ..........@.....
00000090: 0010400000000000 3000000000000000 // ..@.....0.......
```
By default groups are separated by spaces, but you can change this using `-s` or `--group-separator`.
```bash
$ hhh -b4 -g4 -s", " test_files/hello | head -10
00000000: 7f454c46, 02010100, 00000000, 00000000 // .ELF............
00000010: 02003e00, 01000000, 00104000, 00000000 // ..>.......@.....
00000020: 40000000, 00000000, 40110000, 00000000 // @.......@.......
00000030: 00000000, 40003800, 02004000, 05000400 // ....@.8...@.....
00000040: 01000000, 04000000, 00000000, 00000000 // ................
00000050: 00004000, 00000000, 00004000, 00000000 // ..@.......@.....
00000060: b0000000, 00000000, b0000000, 00000000 // ................
00000070: 00100000, 00000000, 01000000, 05000000 // ................
00000080: 00100000, 00000000, 00104000, 00000000 // ..........@.....
00000090: 00104000, 00000000, 30000000, 00000000 // ..@.....0.......
```
If you specify `-g0` then **hhh** will choose a number of groups based on the terminal width.
## Byte Order
Note that the bytes in a group are presented in the same order as they occur in the file. You can reverse the byte order within groups using the `--little-endian` switch.
```bash
$ hhh -b8 -g2 --little-endian test_files/hello | head -10
00000000: 00010102464c457f 0000000000000000 // .ELF............
00000010: 00000001003e0002 0000000000401000 // ..>.......@.....
00000020: 0000000000000040 0000000000001140 // @.......@.......
00000030: 0038004000000000 0004000500400002 // ....@.8...@.....
00000040: 0000000400000001 0000000000000000 // ................
00000050: 0000000000400000 0000000000400000 // ..@.......@.....
00000060: 00000000000000b0 00000000000000b0 // ................
00000070: 0000000000001000 0000000500000001 // ................
00000080: 0000000000001000 0000000000401000 // ..........@.....
00000090: 0000000000401000 0000000000000030 // ..@.....0.......
```
## Suppressing the Offsets and ASCII Preview
Suppress the offset printed at the start of each line with `--no-offset`. Suppress the ASCII preview of the line with `--no-ascii`.
```bash
$ hhh -b8 -g2 --no-offset --no-ascii test_files/hello | head -10
7f454c4602010100 0000000000000000
02003e0001000000 0010400000000000
4000000000000000 4011000000000000
0000000040003800 0200400005000400
0100000004000000 0000000000000000
0000400000000000 0000400000000000
b000000000000000 b000000000000000
0010000000000000 0100000005000000
0010000000000000 0010400000000000
0010400000000000 3000000000000000
```
## Selecting a Region
You can tell **hhh** to start at a given file offset with `--start`, and can limit the output to a specified number of bytes with `--count`.
```bash
$ hhh --start=10 --count=100 test_files/hello
0000000a: 00 00 00 00 00 00 02 00 3e 00 01 00 00 00 00 10 // ........>.......
0000001a: 40 00 00 00 00 00 40 00 00 00 00 00 00 00 40 11 // @.....@.......@.
0000002a: 00 00 00 00 00 00 00 00 00 00 40 00 38 00 02 00 // ..........@.8...
0000003a: 40 00 05 00 04 00 01 00 00 00 04 00 00 00 00 00 // @...............
0000004a: 00 00 00 00 00 00 00 00 40 00 00 00 00 00 00 00 // ........@.......
0000005a: 40 00 00 00 00 00 b0 00 00 00 00 00 00 00 b0 00 // @...............
0000006a: 00 00 00 00 // ....
```
## Bias
You can adjust the *displayed* offset using the `--bias` flag with a value. The value must be positive. If you require a negative bias, you can use a [directive][].
```bash
$ hhh --bias=0x1000 test_files/hello | head -10
00001000: 7f 45 4c 46 02 01 01 00 00 00 00 00 00 00 00 00 // .ELF............
00001010: 02 00 3e 00 01 00 00 00 00 10 40 00 00 00 00 00 // ..>.......@.....
00001020: 40 00 00 00 00 00 00 00 40 11 00 00 00 00 00 00 // @.......@.......
00001030: 00 00 00 00 40 00 38 00 02 00 40 00 05 00 04 00 // ....@.8...@.....
00001040: 01 00 00 00 04 00 00 00 00 00 00 00 00 00 00 00 // ................
00001050: 00 00 40 00 00 00 00 00 00 00 40 00 00 00 00 00 // ..@.......@.....
00001060: b0 00 00 00 00 00 00 00 b0 00 00 00 00 00 00 00 // ................
00001070: 00 10 00 00 00 00 00 00 01 00 00 00 05 00 00 00 // ................
00001080: 00 10 00 00 00 00 00 00 00 10 40 00 00 00 00 00 // ..........@.....
00001090: 00 10 40 00 00 00 00 00 30 00 00 00 00 00 00 00 // ..@.....0.......
```
```bash
$ hhh --start=10 --bias=-10 --count=100 test_files/hello
00000000: 00 00 00 00 00 00 02 00 3e 00 01 00 00 00 00 10 // ........>.......
00000010: 40 00 00 00 00 00 40 00 00 00 00 00 00 00 40 11 // @.....@.......@.
00000020: 00 00 00 00 00 00 00 00 00 00 40 00 38 00 02 00 // ..........@.8...
00000030: 40 00 05 00 04 00 01 00 00 00 04 00 00 00 00 00 // @...............
00000040: 00 00 00 00 00 00 00 00 40 00 00 00 00 00 00 00 // ........@.......
00000050: 40 00 00 00 00 00 b0 00 00 00 00 00 00 00 b0 00 // @...............
00000060: 00 00 00 00 // ....
```
## Skipping Zero Lines
If a line consists entirely of zeros, you can suppress it with `--skip-zeros`.
```bash
$ hhh --skip-zeros test_files/hello
00000000: 7f 45 4c 46 02 01 01 00 00 00 00 00 00 00 00 00 // .ELF............
00000010: 02 00 3e 00 01 00 00 00 00 10 40 00 00 00 00 00 // ..>.......@.....
00000020: 40 00 00 00 00 00 00 00 40 11 00 00 00 00 00 00 // @.......@.......
00000030: 00 00 00 00 40 00 38 00 02 00 40 00 05 00 04 00 // ....@.8...@.....
00000040: 01 00 00 00 04 00 00 00 00 00 00 00 00 00 00 00 // ................
00000050: 00 00 40 00 00 00 00 00 00 00 40 00 00 00 00 00 // ..@.......@.....
00000060: b0 00 00 00 00 00 00 00 b0 00 00 00 00 00 00 00 // ................
00000070: 00 10 00 00 00 00 00 00 01 00 00 00 05 00 00 00 // ................
00000080: 00 10 00 00 00 00 00 00 00 10 40 00 00 00 00 00 // ..........@.....
00000090: 00 10 40 00 00 00 00 00 30 00 00 00 00 00 00 00 // ..@.....0.......
000000a0: 30 00 00 00 00 00 00 00 00 10 00 00 00 00 00 00 // 0...............
00001000: b8 01 00 00 00 bf 01 00 00 00 48 8d 35 11 00 00 // ..........H.5...
00001010: 00 ba 0e 00 00 00 0f 05 b8 3c 00 00 00 31 ff 0f // .........<...1..
00001020: 05 f4 48 65 6c 6c 6f 2c 20 77 6f 72 6c 64 21 0a // ..Hello,.world!.
```
In the above the lines between `000000a0` and `00001000` consist entirely of zeros, and are suppressed.
## Offset Padding
By default the offset is displayed as an eight-digit hexadecimal number. You can change this with the `--offset-width` switch, which must be a non-zero value less than 256.
```bash
$ hhh --offset-width=2 --skip-zeros test_files/hello
00: 7f 45 4c 46 02 01 01 00 00 00 00 00 00 00 00 00 // .ELF............
10: 02 00 3e 00 01 00 00 00 00 10 40 00 00 00 00 00 // ..>.......@.....
20: 40 00 00 00 00 00 00 00 40 11 00 00 00 00 00 00 // @.......@.......
30: 00 00 00 00 40 00 38 00 02 00 40 00 05 00 04 00 // ....@.8...@.....
40: 01 00 00 00 04 00 00 00 00 00 00 00 00 00 00 00 // ................
50: 00 00 40 00 00 00 00 00 00 00 40 00 00 00 00 00 // ..@.......@.....
60: b0 00 00 00 00 00 00 00 b0 00 00 00 00 00 00 00 // ................
70: 00 10 00 00 00 00 00 00 01 00 00 00 05 00 00 00 // ................
80: 00 10 00 00 00 00 00 00 00 10 40 00 00 00 00 00 // ..........@.....
90: 00 10 40 00 00 00 00 00 30 00 00 00 00 00 00 00 // ..@.....0.......
a0: 30 00 00 00 00 00 00 00 00 10 00 00 00 00 00 00 // 0...............
1000: b8 01 00 00 00 bf 01 00 00 00 48 8d 35 11 00 00 // ..........H.5...
1010: 00 ba 0e 00 00 00 0f 05 b8 3c 00 00 00 31 ff 0f // .........<...1..
1020: 05 f4 48 65 6c 6c 6f 2c 20 77 6f 72 6c 64 21 0a // ..Hello,.world!.
```
## Radix Prefixes
You can tell **hhh** to output a `0x` in front of every value with `--radix-prefixes`.
```bash
$ hhh --radix-prefixes -g8 test_files/hello | head -10
0x00000000: 0x7f 0x45 0x4c 0x46 0x02 0x01 0x01 0x00 // .ELF....
0x00000008: 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 // ........
0x00000010: 0x02 0x00 0x3e 0x00 0x01 0x00 0x00 0x00 // ..>.....
0x00000018: 0x00 0x10 0x40 0x00 0x00 0x00 0x00 0x00 // ..@.....
0x00000020: 0x40 0x00 0x00 0x00 0x00 0x00 0x00 0x00 // @.......
0x00000028: 0x40 0x11 0x00 0x00 0x00 0x00 0x00 0x00 // @.......
0x00000030: 0x00 0x00 0x00 0x00 0x40 0x00 0x38 0x00 // ....@.8.
0x00000038: 0x02 0x00 0x40 0x00 0x05 0x00 0x04 0x00 // ..@.....
0x00000040: 0x01 0x00 0x00 0x00 0x04 0x00 0x00 0x00 // ........
0x00000048: 0x00 0x00 0x00 0x00 0x00 0x00 0x00 0x00 // ........
```
Using this with `--no-offset`, `--no-ascii`, and `-s", "` creates a text that can be imported into many programming languages.
```bash
$ hhh --radix-prefixes -g8 --no-offset --no-ascii -s", " test_files/hello | head -10
0x7f, 0x45, 0x4c, 0x46, 0x02, 0x01, 0x01, 0x00
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
0x02, 0x00, 0x3e, 0x00, 0x01, 0x00, 0x00, 0x00
0x00, 0x10, 0x40, 0x00, 0x00, 0x00, 0x00, 0x00
0x40, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
0x40, 0x11, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
0x00, 0x00, 0x00, 0x00, 0x40, 0x00, 0x38, 0x00
0x02, 0x00, 0x40, 0x00, 0x05, 0x00, 0x04, 0x00
0x01, 0x00, 0x00, 0x00, 0x04, 0x00, 0x00, 0x00
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00
```
## Metadata
Metadata can be included as comments in the output file by giving the `-m` or `--meta` command line switches, or using the `metadata` directive.
These comments include the command line arguments and switches used to generate the file and the date and time of generation. You can add additional metadata elements using the `-Mname=value` or `--set-meta=name=value` command line switches or the `set-metadata(name, value)` directive.
``` bash
hhh --little-endian -g3 -b8 test_files/hello -MProject=Orion -m | head -10
// Command-Line: "--little-endian" "-g3" "-b8" "test_files/hello" "-MProject=Orion" "-m"
// Project: Orion
// UTC: 2023-10-07 04:39:52.506435470 UTC
00000000: 00010102464c457f 0000000000000000 00000001003e0002 // .ELF..............>.....
00000018: 0000000000401000 0000000000000040 0000000000001140 // ..@.....@.......@.......
00000030: 0038004000000000 0004000500400002 0000000400000001 // ....@.8...@.............
00000048: 0000000000000000 0000000000400000 0000000000400000 // ..........@.......@.....
00000060: 00000000000000b0 00000000000000b0 0000000000001000 // ........................
00000078: 0000000500000001 0000000000001000 0000000000401000 // ..................@.....
00000090: 0000000000401000 0000000000000030 0000000000000030 // ..@.....0.......0.......
```
[directive]: directive.md
