Struct zydis::Formatter

#[repr(C)]
pub struct Formatter<UserData = ()> { /* private fields */ }

Formats decoded instructions to human-readable text.

Implementations

impl Formatter<()>

pub fn new(style: FormatterStyle) -> Self

Creates a new formatter instance (no user-data).

pub fn intel() -> Self

Creates a new formatter for Intel syntax.

Convenience wrapper for Self::new(FormatterStyle::INTEL).

pub fn att() -> Self

Creates a new formatter for AT&T syntax.

Convenience wrapper for Self::new(FormatterStyle::ATT).

impl<UserData> Formatter<UserData>

pub fn set_pre_instruction( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_post_instruction( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_pre_operand( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_post_operand( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_format_instruction( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_format_operand_reg( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_format_operand_mem( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_format_operand_ptr( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_format_operand_imm( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_print_mnemonic( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_print_register( &mut self, new_func: Box<WrappedRegisterFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_print_address_abs( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_print_address_rel( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_print_disp( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_print_imm( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_print_typecast( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_print_prefixes( &mut self, new_func: Box<WrappedGeneralFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn set_print_decorator( &mut self, new_func: Box<WrappedDecoratorFunc<UserData>> ) -> Result<Hook>

Sets the formatter hook to the provided value.

This function accepts a wrapped version of the raw hook. It returns the previous set raw hook.

pub fn raw(&self) -> &Formatter

pub fn new_custom_userdata(style: FormatterStyle) -> Self

Creates a new formatter instance.

pub fn set_property<'this, 'b: 'this>( &'this mut self, prop: FormatterProperty<'b> ) -> Result<()>

Sets the given FormatterProperty on this formatter instance.

pub fn format<const N: usize>( &self, ip: Option<u64>, insn: &Instruction<OperandArrayVec<N>> ) -> Result<String>

Format an instruction as a String.

The ip may be None, in which case relative address formatting is used. Otherwise absolute addresses are used.

pub fn format_into<const N: usize>( &self, ip: Option<u64>, insn: &Instruction<OperandArrayVec<N>>, f: &mut Formatter<'_> ) -> Result

Format an instruction and append it to a fmt::Formatter.

The ip may be None, in which case relative address formatting is used. Otherwise absolute addresses are used.

pub fn format_ex<const N: usize>( &self, ip: Option<u64>, insn: &Instruction<OperandArrayVec<N>>, buffer: &mut OutputBuffer<'_>, user_data: Option<&mut UserData> ) -> Result<()>

Format an instruction into an OutputBuffer.

The ip may be None, in which case relative address formatting is used. Otherwise absolute addresses are used.

This variant is “rawer” than the other format function in that it accepts the raw FFI structs. It further allows the user to pass a custom user_data argument` that is passed to the formatter hooks.

Examples

static INT3: &'static [u8] = &[0xCC];

let mut buffer = [0u8; 256];
let mut buffer = OutputBuffer::new(&mut buffer[..]);

let formatter = Formatter::intel();
let dec = Decoder::new64();

let insn = dec.decode_first::<VisibleOperands>(INT3).unwrap().unwrap();

formatter
    .format_ex(Some(0), &insn, &mut buffer, None)
    .unwrap();

assert_eq!(buffer.as_str().unwrap(), "int3");

pub fn format_operand<const N: usize>( &self, ip: Option<u64>, insn: &Instruction<OperandArrayVec<N>>, buffer: &mut OutputBuffer<'_>, operand_index: usize, user_data: Option<&mut UserData> ) -> Result<()>

Formats just the given operand at operand_index from the given instruction, using buffer for storage.

The ip may be None, in which case relative address formatting is used. Otherwise absolute addresses are used.

user_data may contain any data to pass on to the formatter hooks.

Panics

If operand_index is out of bounds.

pub fn tokenize<'buffer, const N: usize>( &self, ip: Option<u64>, insn: &Instruction<OperandArrayVec<N>>, buffer: &'buffer mut [u8], user_data: Option<&mut UserData> ) -> Result<&'buffer FormatterToken<'buffer>>

Tokenize the given instruction.

The recommended amount of memory to allocate is 256 bytes.

pub fn tokenize_operand<'buffer, const N: usize>( &self, ip: Option<u64>, insn: &Instruction<OperandArrayVec<N>>, buffer: &'buffer mut [u8], operand_index: usize, user_data: Option<&mut UserData> ) -> Result<&'buffer FormatterToken<'buffer>>

Tokenizes the given operand at operand_index.

Examples

static PUSH: &'static [u8] = &[0x51]; // push rcx

let dec = Decoder::new64();
let formatter = Formatter::intel();

let mut buffer = [0; 256];
let insn = dec.decode_first::<VisibleOperands>(PUSH).unwrap().unwrap();
let (ty, val) = formatter
    .tokenize_operand(None, &insn, &mut buffer[..], 0, None)
    .unwrap()
    .value()
    .unwrap();

assert_eq!(ty, TOKEN_REGISTER);
assert_eq!(val, "rcx");

Panics

If operand_index is out of bounds.

pub unsafe fn set_raw_hook(&mut self, hook: Hook) -> Result<Hook>

Sets a raw hook, allowing for customizations along the formatting process.

This is the raw C style version of the formatter hook mechanism. No wrapping occurs, your callback will receive raw pointers. You might want to consider using any of the wrapped variants instead.