Struct Manager 

pub struct Manager { /* private fields */ }

Breakpoint manager that owns breakpoint metadata for a traced process.

Manager keeps track of installed software breakpoints (INT3) and the original bytes they replaced. It provides helpers to install, remove and temporarily save/restore breakpoints. All ptrace operations are performed by this manager and therefore require the tracee to be stopped when called.

Implementations

impl Manager

pub fn new(pid: Pid) -> Self

Create a new Manager for pid.

Arguments

• pid - PID of the traced process this manager will operate on.

Returns

A new Manager ready to install and manage breakpoints for pid.

pub fn set_breakpoint( &mut self, addr: u64, temporary: bool, registered: bool, id: Option<u64>, ) -> Result<Option<u64>>

Set a breakpoint at addr.

Arguments

• addr - The address where the breakpoint should be set.
• temporary - If true the breakpoint is considered temporary and won’t be returned as a Pending event when hit.
• registered - If true allocate or use an id and persist the breakpoint in the manager’s table. If false the breakpoint is not assigned an id.
• id - Optionally provide an explicit id to use when registered is true.

Errors

Returns an error if a ptrace read/write fails while patching memory.

Returns

Returns Ok(Some(id)) when the breakpoint is registered and has an id, Ok(None) when it is not registered.

pub fn handle_breakpoint( &mut self, regs: &mut Registers, ) -> Result<Option<Pending>>

Handle a breakpoint stop at RIP-1.

When the tracee hits an INT3 the RIP points at the instruction after the breakpoint; this method restores the original byte, rewrites RIP to point at the original instruction and writes the registers back.

Arguments

• regs - Mutable register snapshot for the stopped tracee.

Errors

Returns an error if ptrace operations fail while restoring the original instruction or writing registers.

Returns

Returns Ok(Some(Pending)) for non-temporary breakpoints that need further processing (reinstallation), or Ok(None) when nothing needs to be done.

pub fn delete_breakpoint(&mut self, id: u64) -> Result<()>

Delete a registered breakpoint by id.

Arguments

• id - The identifier of the breakpoint to delete.

Errors

Returns ENODATA when no breakpoint with the given id exists or when the ptrace write to restore the original byte fails.

Returns

Returns Ok(()) on success; returns Err if no matching breakpoint exists or if restoring the original byte fails.

pub fn save_breakpoint(&mut self, addr: u64) -> Result<()>

Temporarily remove (save) the breakpoint at addr.

This is used when single-stepping over an instruction that previously had an INT3 installed: we restore the original byte so the single step executes the original instruction. The manager records addr in its saved slot so restore_breakpoint can re-install it later.

Arguments

• addr - Address of the breakpoint to temporarily remove (save).

Errors

Returns EBUSY if there is already a saved breakpoint in progress. Returns an error if the underlying ptrace restore fails.

pub fn restore_breakpoint(&mut self) -> Result<()>

Reinstall a previously saved breakpoint (if any).

Errors

Returns an error if reinstallation via ptrace write fails.

Returns

Returns Ok(()) on success. If there was no saved breakpoint this method is a no-op and still returns Ok(()).

Trait Implementations

impl Display for Manager

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

Formats the value using the given formatter.