Struct gdbmi::Gdb

pub struct Gdb { /* fields omitted */ }

Implementations

impl Gdb

Some methods take an option timeout. If you provide None the default timeout will be used.

Warning

Never pass untrusted user input.

GDB is designed around the assumption the user is running it on their own machine, and therefore doesn’t need to be defended against.

We do some escaping before passing inputs to GDB to try and protect against users mistakenly entering nonsensical inputs (like "--type" as a variable name), but defending against untrusted users is out-of-scope. If you’re exposing your app to untrusted users you probably want a sandbox.

pub fn spawn(target: impl Into<Utf8PathBuf>) -> Result<Self>

Spawn a gdb process to debug target.

By default we use rust-gdb to support pretty-printing rust symbols and a timeout of five seconds.

Use GdbBuilder if you need greater control over the configuration.

pub async fn status(&self) -> Result<Status, TimeoutError>

Get the current status

Note: The status is refreshed when gdb sends us notifications. Calling this function just fetches the cached status.

pub async fn next_status(
    &self,
    current: Status,
    timeout: Option<Duration>
) -> Result<Status, TimeoutError>

Wait for the status to change and return the new status.

To avoid missing a status change right before your request is processed, submit what you think the current status is. If you’re wrong, you’ll get back the current status instead of waiting for the next one.

pub async fn await_stopped(
    &self,
    timeout: Option<Duration>
) -> Result<Stopped, TimeoutError>

Wait until the status is Status::Stopped and then return the status.

pub async fn await_status<P>(
    &self,
    pred: P,
    timeout: Option<Duration>
) -> Result<Status, TimeoutError> where
    P: Fn(&Status) -> bool + Send + Sync + 'static, 

Provide each status we get to a function you provide. When the function returns true, return that status.

let timeout = Duration::from_secs(10);
let status = gdb
    .await_status(|s| s == &Status::Running, Some(timeout))
    .await?;

pub async fn exec_run(&self) -> Result<(), Error>

Run the target from the start.

Under rr this merely resets the program counter to the start, you need to also call Self::exec_continue to actally start running.

pub async fn exec_continue(&self) -> Result<(), Error>

pub async fn exec_continue_reverse(&self) -> Result<(), Error>

pub async fn exec_finish(&self) -> Result<(), Error>

pub async fn exec_finish_reverse(&self) -> Result<(), Error>

Resume the reverse execution of the inferior program until the point where current function was called.

pub async fn exec_step(&self) -> Result<(), Error>

pub async fn exec_step_reverse(&self) -> Result<(), Error>

pub async fn break_insert(&self, at: LineSpec) -> Result<Breakpoint, Error>

pub async fn break_disable<'a, I>(&self, breakpoints: I) -> Result<(), Error> where
    I: IntoIterator<Item = &'a Breakpoint>, 

pub async fn break_delete<'a, I>(&self, breakpoints: I) -> Result<(), Error> where
    I: IntoIterator<Item = &'a Breakpoint>, 

pub async fn enable_filter_frames(&self) -> Result<(), Error>

GDB allows Python-based frame filters to affect the output of the MI commands relating to stack traces. As there is no way to implement this in a fully backward-compatible way, a front end must request that this functionality be enabled. Once enabled, this feature cannot be disabled.

Note that if Python support has not been compiled into GDB, this command will still succeed (and do nothing).

pub async fn stack_depth(&self, max: Option<u32>) -> Result<u32, Error>

If max is provided, don’t count beyond it.

pub async fn stack_list_variables(
    &self,
    frame_filters: bool
) -> Result<Vec<Variable>, Error>

List the arguments and local variables in the current stack frame.

Complex variables (structs, arrays, and unions) will not have a type.

If frame_filters is false python frame filters will be skipped

pub async fn stack_info_frame(&self) -> Result<Frame, Error>

pub async fn symbol_info_functions(
    &self
) -> Result<HashMap<Utf8PathBuf, Vec<Function>>, Error>

pub async fn symbol_info_functions_re(
    &self,
    name_regex: &str
) -> Result<HashMap<Utf8PathBuf, Vec<Function>>, Error>

Returns the functions whose name matches name_regex.

Gdb by default counts matches against substrings. For example, my_crate:: will match core::ptr::drop_in_place<simple::DraftPost> (the monomorphic version of a standard library function). If you only want to match functions in my_crate, pass ^my_crate::.

pub async fn save_checkpoint(&self) -> Result<Checkpoint, Error>

Save a snapshot of the current program state to come back to later.

If this isn’t supported you may get an unhelpful error such as

syntax error in expression, near `lseek (0, 0, 1)'.

I use this with the time travelling debugger rr, as gdb on my machine doesn’t support snapshots.

pub async fn goto_checkpoint(&self, checkpoint: Checkpoint) -> Result<(), Error>

pub async fn raw_cmd(&self, msg: impl Into<String>) -> Result<Response, Error>

Execute a command for a response.

Your command will be prefixed with a token and suffixed with a newline.

pub async fn raw_console_cmd(
    &self,
    msg: impl Into<String>
) -> Result<Response, Error>

Execute a console command for a given number of lines of console output.

Console commands are the commands you enter in a normal GDB session, in contrast to the GDB/MI commands designed for programmatic use.

You will need to use this function if the command you need isn’t supported by GDB/MI.

If you need to see the output, use Self::raw_console_cmd_for_output.

pub async fn raw_console_cmd_for_output(
    &self,
    msg: impl AsRef<str>,
    capture_lines: usize
) -> Result<(Response, Vec<String>), Error>

Prefer Self::raw_console_cmd if possible.

Avoid capturing more lines than you need to. Because console output can’t be associated with a command we assume the next capture_lines of output should go to the caller. This means we need to block anyone else from communicating with to GDB until the lines are received or you timeout.

Panics

• capture_lines is zero

pub async fn await_ready(&self) -> Result<(), Error>

Waits until gdb is responsive to commands.

You do not need to call this before sending commands yourself.

pub async fn pop_general(&self) -> Result<Vec<GeneralMessage>, TimeoutError>

Pop any messages gdb has sent that weren’t addressed to any specific request off the buffer and return them.

#[must_use]

pub fn new(cmd: Child, timeout: Duration) -> Self

Spawn the process yourself.

You are responsible for configuring the process to speak version 3 of GDB/MI, and setting stdin, stdout, and stderr to Stdio::piped. The following is roughly what Self::spawn does for you.

let executable = "program-to-debug";
let timeout = Duration::from_secs(5);

let cmd = tokio::process::Command::new("rust-gdb")
   .arg("--interpreter=mi3")
   .arg("--quiet")
   .arg(executable)
   .stdin(Stdio::piped())
   .stdout(Stdio::piped())
   .stderr(Stdio::piped())
   .spawn()?;

let gdb = Gdb::new(cmd, timeout);

See Self::spawn for an explanation of timeout.

pub fn set_timeout(&mut self, timeout: Duration)

Change the timeout used for all async operations

Trait Implementations

impl Debug for Gdb

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

Formats the value using the given formatter.