Struct UnicornHandle 

pub struct UnicornHandle<'a> { /* private fields */ }

Handle used to safely access exposed functions and data of a Unicorn instance.

Implementations

impl<'a> UnicornHandle<'a>

pub fn get_arch(&self) -> Arch

Return the architecture of the current emulator.

pub fn mem_regions(&self) -> Result<Vec<MemRegion>, uc_error>

Returns a vector with the memory regions that are mapped in the emulator.

pub fn mem_read(&self, address: u64, buf: &mut [u8]) -> Result<(), uc_error>

Read a range of bytes from memory at the specified address.

pub fn mem_read_as_vec( &self, address: u64, size: usize, ) -> Result<Vec<u8>, uc_error>

Return a range of bytes from memory at the specified address as vector.

pub fn mem_write(&mut self, address: u64, bytes: &[u8]) -> Result<(), uc_error>

pub fn mem_map_ptr( &mut self, address: u64, size: usize, perms: Permission, ptr: *mut c_void, ) -> Result<(), uc_error>

Map an existing memory region in the emulator at the specified address.

This function is marked unsafe because it is the responsibility of the caller to ensure that size matches the size of the passed buffer, an invalid size value will likely cause a crash in unicorn.

address must be aligned to 4kb or this will return Error::ARG.

size must be a multiple of 4kb or this will return Error::ARG.

ptr is a pointer to the provided memory region that will be used by the emulator.

pub fn mem_map( &mut self, address: u64, size: size_t, perms: Permission, ) -> Result<(), uc_error>

Map a memory region in the emulator at the specified address.

address must be aligned to 4kb or this will return Error::ARG. size must be a multiple of 4kb or this will return Error::ARG.

pub fn mem_unmap(&mut self, address: u64, size: size_t) -> Result<(), uc_error>

Unmap a memory region.

address must be aligned to 4kb or this will return Error::ARG. size must be a multiple of 4kb or this will return Error::ARG.

pub fn mem_protect( &mut self, address: u64, size: size_t, perms: Permission, ) -> Result<(), uc_error>

Set the memory permissions for an existing memory region.

address must be aligned to 4kb or this will return Error::ARG. size must be a multiple of 4kb or this will return Error::ARG.

pub fn reg_write<T: Into<i32>>( &mut self, regid: T, value: u64, ) -> Result<(), uc_error>

Write an unsigned value from a register.

pub fn reg_write_long<T: Into<i32>>( &self, regid: T, value: Box<[u8]>, ) -> Result<(), uc_error>

Write variable sized values into registers.

The user has to make sure that the buffer length matches the register size. This adds support for registers >64 bit (GDTR/IDTR, XMM, YMM, ZMM (x86); Q, V (arm64)).

pub fn reg_read<T: Into<i32>>(&self, regid: T) -> Result<u64, uc_error>

Read an unsigned value from a register.

Not to be used with registers larger than 64 bit.

pub fn reg_read_long<T: Into<i32>>( &self, regid: T, ) -> Result<Box<[u8]>, uc_error>

Read 128, 256 or 512 bit register value into heap allocated byte array.

This adds safe support for registers >64 bit (GDTR/IDTR, XMM, YMM, ZMM (x86); Q, V (arm64)).

pub fn reg_read_i32<T: Into<i32>>(&self, regid: T) -> Result<i32, uc_error>

Read a signed 32-bit value from a register.

pub fn add_code_hook<F>( &mut self, begin: u64, end: u64, callback: F, ) -> Result<*mut c_void, uc_error>

where F: FnMut(UnicornHandle<'_>, u64, u32) + 'static,

Add a code hook.

pub fn add_block_hook<F>( &mut self, callback: F, ) -> Result<*mut c_void, uc_error>

where F: FnMut(UnicornHandle<'_>, u64, u32) + 'static,

Add a block hook.

pub fn add_mem_hook<F>( &mut self, hook_type: HookType, begin: u64, end: u64, callback: F, ) -> Result<*mut c_void, uc_error>

where F: FnMut(UnicornHandle<'_>, MemType, u64, usize, i64) + 'static,

Add a memory hook.

pub fn add_intr_hook<F>(&mut self, callback: F) -> Result<*mut c_void, uc_error>

where F: FnMut(UnicornHandle<'_>, u32) + 'static,

Add an interrupt hook.

pub fn add_insn_in_hook<F>( &mut self, callback: F, ) -> Result<*mut c_void, uc_error>

where F: FnMut(UnicornHandle<'_>, u32, usize) + 'static,

Add hook for x86 IN instruction.

pub fn add_insn_out_hook<F>( &mut self, callback: F, ) -> Result<*mut c_void, uc_error>

where F: FnMut(UnicornHandle<'_>, u32, usize, u32) + 'static,

Add hook for x86 OUT instruction.

pub fn add_insn_sys_hook<F>( &mut self, insn_type: InsnSysX86, begin: u64, end: u64, callback: F, ) -> Result<*mut c_void, uc_error>

where F: FnMut(UnicornHandle<'_>) + 'static,

Add hook for x86 SYSCALL or SYSENTER.

pub fn remove_hook(&mut self, hook: *mut c_void) -> Result<(), uc_error>

Remove a hook.

hook is the value returned by add_*_hook functions.

pub fn context_alloc(&self) -> Result<Context, uc_error>

Allocate and return an empty Unicorn context.

To be populated via context_save.

pub fn context_save(&self, context: &mut Context) -> Result<(), uc_error>

Save current Unicorn context to previously allocated Context struct.

pub fn context_init(&self) -> Result<Context, uc_error>

Allocate and return a Context struct initialized with the current CPU context.

This can be used for fast rollbacks with context_restore. In case of many non-concurrent context saves, use context_alloc and *_save individually to avoid unnecessary allocations.

pub fn context_restore(&self, context: &Context) -> Result<(), uc_error>

Restore a previously saved Unicorn context.

Perform a quick rollback of the CPU context, including registers and some internal metadata. Contexts may not be shared across engine instances with differing arches or modes. Memory has to be restored manually, if needed.

pub fn emu_start( &mut self, begin: u64, until: u64, timeout: u64, count: usize, ) -> Result<(), uc_error>

Emulate machine code for a specified duration.

begin is the address where to start the emulation. The emulation stops if until is hit. timeout specifies a duration in microseconds after which the emulation is stopped (infinite execution if set to 0). count is the maximum number of instructions to emulate (emulate all the available instructions if set to 0).

pub fn emu_stop(&mut self) -> Result<(), uc_error>

Stop the emulation.

This is usually called from callback function in hooks. NOTE: For now, this will stop the execution only after the current block.

pub fn query(&self, query: Query) -> Result<usize, uc_error>

Query the internal status of the engine.

supported: MODE, PAGE_SIZE, ARCH

Trait Implementations

impl<'a> Debug for UnicornHandle<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.