Crate capstone_git

Crate capstone_git 

Source
Expand description

§capstone-rs-git

This is a fork of capstone-rs that is sourced directly from the master branch of the upstream repository, allowing the use of certain unreleased features.

The purpose of re-publishing the crate is to allow libraries that also depend on said unreleased features to be published on crates.io.

API Documentation

Bindings to the capstone library disassembly framework.

The Capstone struct is the main interface to the library.

§Requirements

capstone-rs uses the capstone-sys crate to provide the low-level bindings to the Capstone C library.

See the capstone-sys page for the requirements and supported platforms.

  • Minimum Rust Version: 1.81.0

§Example

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() {
    let cs = Capstone::new()
        .x86()
        .mode(arch::x86::ArchMode::Mode64)
        .syntax(arch::x86::ArchSyntax::Att)
        .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();

        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())),
        ];

        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:

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/ directory. More complex demos welcome!

§Features

  • full†: do not compile Capstone C library in diet mode
  • std†: enable std-only features, such as the Error trait
  • use_bindgen: run bindgen to generate Rust bindings to Capstone C library instead of using pre-generated bindings (not recommended)
  • arch_$ARCH†: enable arch $ARCH support in capstone, e.g. arch_arm64 enables arch arm64 support
  • support_all_archs†: enable all archs available in capstone, imply all arch_$ARCH features
  • check_only: do not compile and link capstone C library, you can enable it to speed up cargo check by 5x

†: enabled by default

§Reporting Issues

Please open a Github issue

§Author

You may find a full list of contributors on Github.

§License

MIT

Modules§

InsnGroupType
arch
Contains architecture-specific types and modules
prelude
Contains items that you probably want to always import

Macros§

define_cs_enum_wrapper_reverse
Define Rust enum that is created from C enum
define_impl_bitmask
Defines getters for a bitmask

Structs§

Capstone
An instance of the capstone disassembler
DisasmIter
Structure to handle iterative disassembly.
EmptyExtraModeIter
Represents an empty set of ExtraMode.
Insn
A single disassembled CPU instruction.
InsnDetail
Contains architecture-independent details about an Insn.
InsnGroupId
Represents the group an instruction belongs to, which may be architecture-specific.
InsnId
Represents an instruction id, which may be architecture-specific.
Instructions
Represents a slice of Insn returned by Capstone disasm*() methods.
OwnedInsn
A single disassembled CPU instruction that lives on the Rust heap.
RegAccessRef
RegId
Represents an register id, which is architecture-specific.

Enums§

AccessType
Represents how the operand is accessed.
Arch
Architectures for the disassembler
Endian
Disassembler endianness
Error
An error enum for this library
ExtraMode
Extra modes or features that can be enabled with some modes
Mode
Disassembler modes
Syntax
Disassembly syntax

Statics§

NO_EXTRA_MODE
Represents that no extra modes are enabled. Can be passed to Capstone::new_raw() as the extra_mode argument.

Traits§

EnumList
A C-like enum can list its variants

Type Aliases§

CsResult
InsnGroupIdInt
Integer type used in InsnGroupId
InsnIdInt
Integer type used in InsnId
RegAccessType
Previously the enum was called RegAccessType, see issue #135 Maintain compatibility with legacy code
RegIdInt
Integer type used in RegId