1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
# capstone-rs
[](https://crates.io/crates/capstone)
Linux/macOS/Windows [](https://github.com/capstone-rust/capstone-rs/actions)
|
FreeBSD [](https://cirrus-ci.com/github/capstone-rust/capstone-rs)
[](https://codecov.io/gh/capstone-rust/capstone-rs)
**[API Documentation](https://docs.rs/capstone/)**
Bindings to the [capstone library][upstream] disassembly framework.
The `Capstone` struct is the main interface to the library.
# Requirements
`capstone-rs` uses the [`capstone-sys`](capstone-sys) crate to provide the low-level bindings to the Capstone C library.
See the [`capstone-sys`](capstone-sys) page for the requirements and supported platforms.
* Minimum Rust Version: `1.70.0`
# Example
```rust
extern crate capstone;
use capstone::prelude::*;
const X86_CODE: &'static [u8] = b"\x55\x48\x8b\x05\xb8\x13\x00\x00\xe9\x14\x9e\x08\x00\x45\x31\xe4";
/// Print register names
fn reg_names(cs: &Capstone, regs: &[RegId]) -> String {
let names: Vec<String> = regs.iter().map(|&x| cs.reg_name(x).unwrap()).collect();
names.join(", ")
}
/// Print instruction group names
fn group_names(cs: &Capstone, regs: &[InsnGroupId]) -> String {
let names: Vec<String> = regs.iter().map(|&x| cs.group_name(x).unwrap()).collect();
names.join(", ")
}
fn main() {
#[cfg(feature = "full")]
let cs = Capstone::new()
.x86()
.mode(arch::x86::ArchMode::Mode64)
.syntax(arch::x86::ArchSyntax::Att)
.detail(true)
.build()
.expect("Failed to create Capstone object");
#[cfg(not(feature = "full"))]
let cs = Capstone::new()
.x86()
.mode(arch::x86::ArchMode::Mode64)
.detail(true)
.build()
.expect("Failed to create Capstone object");
let insns = cs.disasm_all(X86_CODE, 0x1000)
.expect("Failed to disassemble");
println!("Found {} instructions", insns.len());
for i in insns.as_ref() {
println!();
println!("{}", i);
let detail: InsnDetail = cs.insn_detail(&i).expect("Failed to get insn detail");
let arch_detail: ArchDetail = detail.arch_detail();
let ops = arch_detail.operands();
#[cfg(feature = "full")]
let output: &[(&str, String)] = &[
("insn id:", format!("{:?}", i.id().0)),
("bytes:", format!("{:?}", i.bytes())),
("read regs:", reg_names(&cs, detail.regs_read())),
("write regs:", reg_names(&cs, detail.regs_write())),
("insn groups:", group_names(&cs, detail.groups())),
];
#[cfg(not(feature = "full"))]
let output: &[(&str, String)] = &[
("insn id:", format!("{:?}", i.id().0)),
("bytes:", format!("{:?}", i.bytes())),
];
for &(ref name, ref message) in output.iter() {
println!("{:4}{:12} {}", "", name, message);
}
println!("{:4}operands: {}", "", ops.len());
for op in ops {
println!("{:8}{:?}", "", op);
}
}
}
```
Produces:
```plain
Found 4 instructions
0x1000: pushq %rbp
read regs: rsp
write regs: rsp
insn groups: mode64
0x1001: movq 0x13b8(%rip), %rax
read regs:
write regs:
insn groups:
0x1008: jmp 0x8ae21
read regs:
write regs:
insn groups: jump
0x100d: xorl %r12d, %r12d
read regs:
write regs: rflags
insn groups:
```
To see more demos, see the [`examples/`](capstone-rs/examples) directory.
More complex demos welcome!
# Features
- `full`<sup>†</sup>: do not compile Capstone C library in
[diet mode](https://www.capstone-engine.org/diet.html)
- `std`<sup>†</sup>: enable `std`-only features, such as the
[`Error` trait](https://doc.rust-lang.org/std/error/trait.Error.html)
- `use_bindgen`: run `bindgen` to generate Rust bindings to Capstone C library
instead of using pre-generated bindings (not recommended).
<sup>†</sup>: enabled by default
# Reporting Issues
Please open a [Github issue](https://github.com/capstone-rust/capstone-rs/issues)
# Author
- Library Author: Nguyen Anh Quynh
- Binding Author(s):
- m4b <m4b.github.io@gmail.com>
- Richo Healey <richo@psych0tik.net>
- Travis Finkenauer <tmfinken@gmail.com>
You may find a [full list of contributors on Github](https://github.com/capstone-rust/capstone-rs/graphs/contributors).
# License
[MIT](capstone-rs/LICENSE)
[upstream]: https://www.capstone-engine.org/
|
