Struct Debugger 

pub struct Debugger { /* private fields */ }

Main structure of bug-stalker, control debugee state and provides application functionality.

Implementations

impl Debugger

pub fn async_backtrace(&mut self) -> Result<AsyncBacktrace, Error>

pub fn async_step_over(&mut self) -> Result<(), Error>

pub fn async_step_out(&mut self) -> Result<(), Error>

Wait for current task ends.

impl Debugger

pub fn set_breakpoint_at_addr( &mut self, addr: RelocatedAddress, ) -> Result<BreakpointView<'_>, Error>

Create and enable breakpoint at debugee address space

Arguments

• addr: address where debugee must be stopped

Errors

Return [SetupError::PlaceNotFound] if no place found for address, return [BreakpointError::DebugInformation] if errors occur while fetching debug information.

pub fn remove_breakpoint( &mut self, addr: Address, ) -> Result<Option<BreakpointView<'_>>, Error>

Disable and remove a breakpoint by it address.

Arguments

• addr: breakpoint address

pub fn remove_breakpoint_by_number( &mut self, number: u32, ) -> Result<Option<BreakpointView<'_>>, Error>

Disable and remove a breakpoint by it number.

Arguments

• number: breakpoint number

pub fn remove_breakpoints_at_addresses( &mut self, addresses: impl Iterator<Item = Address>, ) -> Result<Vec<BreakpointView<'_>>, Error>

Remove breakpoint from instruction.

Arguments

• addresses: address of instruction where breakpoint may be found.

pub fn set_breakpoint_at_fn( &mut self, template: &str, ) -> Result<Vec<BreakpointView<'_>>, Error>

Create and enable breakpoint at debugee address space on the following function start.

Arguments

• template: template for searchin functions where debugee must be stopped

Errors

Return [SetupError::PlaceNotFound] if function not found, return [BreakpointError::DebugInformation] if errors occur while fetching debug information.

pub fn remove_breakpoint_at_fn( &mut self, template: &str, ) -> Result<Vec<BreakpointView<'_>>, Error>

Disable and remove breakpoint from function start.

Arguments

• template: template for searchin functions where breakpoints must be deleted

pub fn set_breakpoint_at_line( &mut self, fine_path_tpl: &str, line: u64, ) -> Result<Vec<BreakpointView<'_>>, Error>

Create and enable breakpoint at the following file and line number.

Arguments

• fine_name: file name (ex: “main.rs”)
• line: line number

Errors

Return [SetupError::PlaceNotFound] if line or file not exist, return [BreakpointError::DebugInformation] if errors occur while fetching debug information.

pub fn remove_breakpoint_at_line( &mut self, fine_name_tpl: &str, line: u64, ) -> Result<Vec<BreakpointView<'_>>, Error>

Disable and remove breakpoint at the following file and line number.

Arguments

• fine_name: file name (ex: “main.rs”)
• line: line number

pub fn set_transparent_breakpoint( &mut self, request: CreateTransparentBreakpointRequest, ) -> Result<(), Error>

Create and enable transparent breakpoint.

Arguments

• request: transparent breakpoint parameters

pub fn breakpoints_snapshot(&self) -> Vec<BreakpointView<'_>>

Return list of breakpoints.

pub fn add_deferred_at_addr(&mut self, addr: RelocatedAddress)

Add new deferred breakpoint by address in debugee address space.

pub fn add_deferred_at_function(&mut self, function: &str)

Add new deferred breakpoint by function name.

pub fn add_deferred_at_line(&mut self, file: &str, line: u64)

Add new deferred breakpoint by file and line.

pub fn refresh_deferred(&mut self) -> Vec<Error>

Refresh deferred breakpoints. Trying to set breakpoint if success - remove breakpoint from a deferred list.

impl Debugger

pub fn call( &mut self, fn_name: &str, arguments: &[Literal], ) -> Result<(), Error>

Do a function call.

Arguments

• fn_name: function to call.
• arguments: list of literals.

impl Debugger

pub fn set_watchpoint_on_expr( &mut self, expr_source: &str, dqe: Dqe, condition: BreakCondition, ) -> Result<WatchpointView<'_>, Error>

Set a new watchpoint on a result of DQE.

Arguments

• expr_source: expression string
• dqe: DQE
• condition: condition for activating a watchpoint

pub fn set_watchpoint_on_memory( &mut self, addr: RelocatedAddress, size: BreakSize, condition: BreakCondition, temporary: bool, ) -> Result<WatchpointView<'_>, Error>

Set a new watchpoint on a memory location

Arguments

• addr: address in debugee memory
• size: size of debugee memory location
• condition: condition for activating a watchpoint

pub fn remove_watchpoint_by_number( &mut self, num: u32, ) -> Result<Option<WatchpointView<'_>>, Error>

Remove watchpoint by its number

Arguments

• num: watchpoint number

pub fn remove_watchpoint_by_addr( &mut self, addr: RelocatedAddress, ) -> Result<Option<WatchpointView<'_>>, Error>

Remove watchpoint by observed address in debugee memory.

Arguments

• addr: address in debugee memory

pub fn remove_watchpoint_by_expr( &mut self, dqe: Dqe, ) -> Result<Option<WatchpointView<'_>>, Error>

Remove watchpoint by DQE, which result observed.

Arguments

• dqe: DQE

pub fn watchpoint_list(&self) -> Vec<WatchpointView<'_>>

Return a list of all watchpoints.

impl Debugger

pub fn get_oracle(&self, name: &str) -> Option<&dyn Oracle>

Return installed oracle, or None if oracle not found or not installed.

Arguments

• name: oracle name

pub fn get_oracle_arc(&self, name: &str) -> Option<Arc<dyn Oracle>>

Same as get_oracle but return an Arc<dyn Oracle>

pub fn all_oracles(&self) -> impl Iterator<Item = &dyn Oracle>

Return all oracles.

pub fn all_oracles_arc(&self) -> impl Iterator<Item = Arc<dyn Oracle>> + '_

Same as all_oracles but return iterator over Arc<dyn Oracle>

pub fn process(&self) -> &Child<Installed>

pub fn set_hook(&mut self, hooks: impl EventHook + 'static)

pub fn ecx(&self) -> &ExplorationContext

Return last set exploration context.

pub fn restart_debugee(&mut self) -> Result<Pid, Error>

Restart debugee by recreating debugee process, save all user-defined breakpoints. Return when new debugee stopped or ends.

! change exploration context

pub fn start_debugee(&mut self) -> Result<(), Error>

Start and execute debugee. Return when debugee stopped or ends.

Errors

Return error if debugee already run or execution fails.

pub fn start_debugee_force(&mut self) -> Result<(), Error>

Start and execute debugee. Restart if debugee already started. Return when debugee stopped or ends.

pub fn dry_start_debugee(&mut self) -> Result<(), Error>

Dry start debugee. Return immediately.

Errors

Return error if debugee already runs.

pub fn continue_debugee(&mut self) -> Result<(), Error>

Continue debugee execution.

pub fn get_symbols(&self, regex: &str) -> Result<Vec<Symbol<'_>>, Error>

Return list of symbols matching regular expression.

Arguments

• regex: regular expression

pub fn frame_info(&self) -> Result<FrameInfo, Error>

Return in focus frame information.

pub fn set_frame_into_focus(&mut self, num: u32) -> Result<u32, Error>

Set new frame into focus.

Arguments

• num: frame number in backtrace

pub fn step_into(&mut self) -> Result<(), Error>

Do a single step (until debugee reaches a different source line).

! change exploration context

pub fn stepi(&mut self) -> Result<(), Error>

Move in focus thread to the next instruction.

! change exploration context

pub fn thread_state(&self) -> Result<Vec<ThreadSnapshot>, Error>

Return list of currently running debugee threads.

pub fn set_thread_into_focus(&mut self, num: u32) -> Result<Tracee, Error>

Sets the thread into focus.

Arguments

• num: thread number

pub fn backtrace(&self, pid: Pid) -> Result<Backtrace, Error>

Return stack trace.

Arguments

• pid: thread id

pub fn read_memory(&self, addr: usize, read_n: usize) -> Result<Vec<u8>, Error>

Read N bytes from a debugee process.

Arguments

• addr: address in debugee address space where reads
• read_n: read byte count

pub fn write_memory( &self, addr: uintptr_t, value: uintptr_t, ) -> Result<(), Error>

Write sizeof(uintptr_t) bytes in debugee address space. Note that little endian byte order will be used when writing.

Arguments

• addr: address to write
• value: value to write

pub fn step_out(&mut self) -> Result<(), Error>

Move to higher stack frame.

pub fn step_over(&mut self) -> Result<(), Error>

Do debugee step (over subroutine calls to).

pub fn read_local_variables(&self) -> Result<Vec<QueryResult<'_>>, Error>

Reads all local variables from current function in current thread.

pub fn read_variable( &self, select_expr: Dqe, ) -> Result<Vec<QueryResult<'_>>, Error>

Reads any variable from the current thread, uses a select expression to filter variables and fetch their properties (such as structure fields or array elements).

Arguments

• select_expr: data query expression

pub fn read_variable_names( &self, select_expr: Dqe, ) -> Result<Vec<String>, Error>

Reads any variable from the current thread, uses a select expression to filter variables and return their names.

Arguments

• select_expr: data query expression

pub fn read_argument( &self, select_expr: Dqe, ) -> Result<Vec<QueryResult<'_>>, Error>

Reads any argument from the current function, uses a select expression to filter variables and fetch their properties (such as structure fields or array elements).

Arguments

• select_expr: data query expression

pub fn read_argument_names( &self, select_expr: Dqe, ) -> Result<Vec<String>, Error>

Reads any argument from the current function, uses a select expression to filter arguments and return their names.

Arguments

• select_expr: data query expression

pub fn get_register_value(&self, register_name: &str) -> Result<u64, Error>

Return following register value.

Arguments

• register_name: x86-64 register name (ex: rip)

pub fn current_thread_registers_at_pc( &self, pc: RelocatedAddress, ) -> Result<DwarfRegisterMap, Error>

Return registers dump for on focus thread at instruction defined by pc.

Arguments

• pc: program counter value

pub fn set_register_value( &self, register_name: &str, val: u64, ) -> Result<(), Error>

Set new register value.

Arguments

• register_name: x86-64 register name (ex: rip)
• val: 8 bite value

pub fn known_files(&self) -> impl Iterator<Item = &PathBuf>

Return list of known files income from dwarf parser.

pub fn shared_libs(&self) -> Vec<RegionInfo>

Return a list of shared libraries.

pub fn disasm(&self) -> Result<FunctionAssembly, Error>

Return a list of disassembled instruction for a function in focus.

pub fn current_function_range(&self) -> Result<FunctionRange<'_>, Error>

Return two place descriptors, at the start and at the end of the current function.

Trait Implementations

impl Drop for Debugger

fn drop(&mut self)

Executes the destructor for this type.