Skip to content

Commit bda7078

Browse files
committed
docs: add guide for hexdump formatting
1 parent 69be136 commit bda7078

1 file changed

Lines changed: 57 additions & 0 deletions

File tree

docs/advanced/hexdump.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,57 @@
1+
# Hex Dump
2+
3+
Every libdestruct object has a `hexdump()` method that returns a classic hex dump of its serialized bytes.
4+
5+
## Basic Usage
6+
7+
```python
8+
from libdestruct import c_int, inflater
9+
10+
memory = bytearray(b"Hello, World!\x00\x00\x00")
11+
lib = inflater(memory)
12+
x = lib.inflate(c_int, 0)
13+
print(x.hexdump())
14+
```
15+
16+
Output format:
17+
18+
```
19+
00000000 48 65 6c 6c |Hell|
20+
```
21+
22+
Each line shows: offset, hex bytes (up to 16 per line), and ASCII representation (non-printable bytes shown as `.`).
23+
24+
## Struct Hex Dump
25+
26+
When called on a struct, `hexdump()` annotates each line with the field names that start on that line:
27+
28+
```python
29+
from libdestruct import struct, c_int, c_long
30+
31+
class player_t(struct):
32+
health: c_int
33+
score: c_long
34+
35+
memory = bytearray(12)
36+
memory[0:4] = (100).to_bytes(4, "little")
37+
memory[4:12] = (9999).to_bytes(8, "little")
38+
39+
player = player_t.from_bytes(memory)
40+
print(player.hexdump())
41+
```
42+
43+
Output:
44+
45+
```
46+
00000000 64 00 00 00 0f 27 00 00 00 00 00 00 |d....'......| health, score
47+
```
48+
49+
## Standalone Utility
50+
51+
The underlying `format_hexdump` function can be used directly:
52+
53+
```python
54+
from libdestruct.common.hexdump import format_hexdump
55+
56+
print(format_hexdump(b"\xde\xad\xbe\xef", base_address=0x1000))
57+
```

0 commit comments

Comments
 (0)