Struct SBProcess 

pub struct SBProcess {
    pub raw: SBProcessRef,
}

The process associated with the target program.

You get a process by attaching to or launching a target program. See SBTarget for details.

Process State

The OS process ID (pid_t) for the process is available via SBProcess::process_id().

The process state can be obtained via SBProcess::state(). It is common to just check to see if the process SBProcess::is_alive(), SBProcess::is_running() or SBProcess::is_stopped().

Once the process is in the Exited state, the SBProcess::exit_status() and SBProcess::exit_description() are available for inspection.

Execution Control

Once you have a process, you can:

• SBProcess::continue_execution()
• SBProcess::stop()
• SBProcess::kill()
• SBProcess::detach()

Threads

The process contains the threads of execution for the target. The available threads can be iterated over with SBProcess::threads():

// Iterate over the threads...
for thread in process.threads() {
    println!("Hello {}!", thread.thread_id());
}
// Or collect them into a vector!
let threads = process.threads().collect::<Vec<SBThread>>();

Specific individual threads can be looked up via SBProcess::thread_by_id() and SBProcess::thread_by_index_id() methods.

Some functions operate on the ‘currently selected thread’. This can retrieved via SBProcess::selected_thread() and set via SBProcess::set_selected_thread(), SBProcess::set_selected_thread_by_id(), or SBProcess::set_selected_thread_by_index_id().

Queues

A process may also have a set of queues associated with it. This is used on macOS, iOS and other Apple operating systems to support debugger integration with libdispatch, also known as GCD or “Grand Central Dispatch”.

The active queues can be iterated over with SBProcess::queues():

// Iterate over the queues...
for queue in process.queues() {
    println!("Hello {}!", queue.queue_id());
}

Events

… to be written …

Fields

raw: SBProcessRef

The underlying raw SBProcessRef.

Implementations

impl SBProcess

pub fn is_valid(&self) -> bool

Check whether or not this is a valid SBProcess value.

pub fn broadcaster_class_name() -> &'static str

pub fn state(&self) -> StateType

The current state of this process (running, stopped, exited, etc.).

See also:

• SBProcess::is_alive()
• SBProcess::is_running()
• SBProcess::is_stopped()
• StateType

pub fn is_alive(&self) -> bool

Returns true if the process is currently alive.

This corresponds to the process being in the Attaching, Launching, Stopped, Running, Stepping, Crashed or Suspended states.

See also:

• SBProcess::is_running()
• SBProcess::is_stopped()
• SBProcess::state()
• StateType

pub fn is_running(&self) -> bool

Returns true if the process is currently running.

This corresponds to the process being in the Running or Stepping states.

See also:

• SBProcess::is_alive()
• SBProcess::is_stopped()
• SBProcess::state()
• StateType

pub fn is_stopped(&self) -> bool

Returns true if the process is currently stopped.

This corresponds to the process being in the Stopped, Crashed, or Suspended states.

See also:

• SBProcess::is_alive()
• SBProcess::is_running()
• SBProcess::state()
• StateType

pub fn exit_status(&self) -> i32

The exit status of the process when the process state is Exited.

See also:

• SBProcess::exit_description()
• SBProcess::state()
• StateType

pub fn exit_description(&self) -> &str

The exit description of the process when the process state is Exited.

See also:

• SBProcess::exit_status()
• SBProcess::state()
• StateType

pub fn process_id(&self) -> lldb_pid_t

Returns the process ID of the process.

pub fn unique_id(&self) -> u32

Returns an integer ID that is guaranteed to be unique across all process instances. This is not the process ID, just a unique integer for comparison and caching purposes.

pub fn address_byte_size(&self) -> u32

Get the size, in bytes, of an address.

pub fn destroy(&self) -> Result<(), SBError>

Kills the process and shuts down all threads that were spawned to track and monitor the process.

pub fn continue_execution(&self) -> Result<(), SBError>

Examples found in repository

examples/basic_synchronous.rs (line 18)

fn main() {
    SBDebugger::initialize();

    let debugger = SBDebugger::create(false);
    debugger.set_asynchronous(false);
    println!("{debugger:?}");

    if let Some(target) = debugger.create_target_simple("/usr/local/bin/servo") {
        println!("{target:?}");

        let launchinfo = SBLaunchInfo::new();
        launchinfo.set_launch_flags(LaunchFlags::STOP_AT_ENTRY);
        match target.launch(launchinfo) {
            Ok(process) => {
                println!("{process:?}");
                let _ = process.continue_execution();
                println!("{process:?}");
            }
            Err(e) => println!("Uhoh: {e:?}"),
        }
    }
    SBDebugger::terminate();
}

pub fn stop(&self) -> Result<(), SBError>

pub fn kill(&self) -> Result<(), SBError>

Same as calling destroy.

pub fn detach(&self) -> Result<(), SBError>

pub fn signal(&self, signal: i32) -> Result<(), SBError>

Send the process a Unix signal.

pub fn get_stdout_all(&self) -> Option<String>

Reads data from the current process’s stdout stream until the end of the stream.

pub fn get_stdout(&self) -> Option<String>

Reads data from the current process’s stdout stream.

pub fn get_stderr_all(&self) -> Option<String>

Reads data from the current process’s stderr stream until the end of the stream.

pub fn get_stderr(&self) -> Option<String>

Reads data from the current process’s stderr stream.

pub fn broadcaster(&self) -> SBBroadcaster

pub fn get_extended_crash_information(&self) -> SBStructuredData

Returns the process’ extended crash information.

pub fn get_num_supported_hardware_watchpoints(&self) -> Result<u32, SBError>

pub fn threads(&self) -> SBProcessThreadIter<'_>

Get an iterator over the threads known to this process instance.

pub fn queues(&self) -> SBProcessQueueIter<'_>

Get an iterator over the queues known to this process instance.

pub fn thread_by_id(&self, thread_id: lldb_tid_t) -> Option<SBThread>

Returns the thread with the given thread ID.

pub fn thread_by_index_id(&self, thread_index_id: u32) -> Option<SBThread>

Returns the thread with the given thread index ID.

pub fn selected_thread(&self) -> SBThread

Returns the currently selected thread.

pub fn set_selected_thread(&self, thread: &SBThread) -> bool

Set the selected thread.

pub fn set_selected_thread_by_id(&self, thread_id: lldb_tid_t) -> bool

Set the selected thread by ID.

pub fn set_selected_thread_by_index_id(&self, thread_index_id: u32) -> bool

Set the selected thread by index ID.

pub fn event_as_process_event(event: &SBEvent) -> Option<SBProcessEvent<'_>>

pub fn save_core(&self, file_name: &str) -> Result<(), SBError>

Save the state of the process in a core file (or mini dump on Windows).

pub fn process_info(&self) -> SBProcessInfo

pub fn allocate_memory( &self, size: usize, permissions: Permissions, ) -> Result<lldb_addr_t, SBError>

Allocate memory within the process.

This function will allocate size bytes in the process’s address space.

The permissions must be any of the Permissions bits OR’d together. The permissions on a given memory allocation can’t be changed after allocation. Note that a block that isn’t set writable can still be written from lldb, just not by the process itself.

Returns the address of the allocated buffer in the process or the error that occurred while trying to allocate.

The allocated memory can be deallocated with SBProcess::deallocate_memory().

Example

if let Ok(data_addr) = process.allocate_memory(1024, Permissions::READABLE) {
    // Do something with the address.
}
if let Ok(code_addr) = process.allocate_memory(1024, Permissions::READABLE | Permissions::EXECUTABLE) {
    // Do something with the address.
}

pub unsafe fn deallocate_memory(&self, ptr: lldb_addr_t) -> Result<(), SBError>

Deallocate memory in the process.

This function will deallocate memory in the process’s address space that was allocated with SBProcess::allocate_memory().

If an error occurs while deallocating, it will be returned.

Safety

The ptr must be a return value from SBProcess::allocate_memory(), pointing to the memory you want to deallocate.

pub fn get_memory_region_info( &self, load_addr: lldb_addr_t, ) -> Result<SBMemoryRegionInfo, SBError>

Query the address load_addr and return the details of the memory region that contains it.

See also:

• SBProcess::get_memory_regions()

pub fn get_memory_regions(&self) -> SBMemoryRegionInfoList

Return the list of memory regions within the process.

See also:

• SBProcess::get_memory_region_info()

pub fn read_memory( &self, addr: lldb_addr_t, buffer: &mut [u8], ) -> Result<(), SBError>

Reads the memory at specified address in the process to the buffer

pub fn write_memory( &self, addr: lldb_addr_t, buffer: &[u8], ) -> Result<(), SBError>

Writes the buffer data to the memory at specified address in the process

pub fn byte_order(&self) -> ByteOrder

Returns the byte order of target process

pub fn load_image(&self, file: &SBFileSpec) -> Result<ImageToken, SBError>

Loads the specified image into the process.

pub fn unload_image(&self, image_token: ImageToken) -> Result<(), SBError>

Unloads the image loaded with load_image.

pub fn target(&self) -> Option<SBTarget>

Returns the SBTarget corresponding to this SBProcess.

This never return None if self is valid.

Trait Implementations

impl Clone for SBProcess

fn clone(&self) -> SBProcess

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for SBProcess

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

Formats the value using the given formatter.

impl Drop for SBProcess

fn drop(&mut self)

Executes the destructor for this type.

impl Send for SBProcess

impl Sync for SBProcess