Struct UnwindCursor 

pub struct UnwindCursor<'a> { /* private fields */ }

A cursor that can move up the call chain and gather information about stack frames.

This struct provides functionality for reading and writing the CPU registers that were preserved in stack frames, as well as moving “up” the call chain to previous function calls. It can be initialized to point to a certain frame using the data in an UnwindContext.

Implementations

impl<'a> UnwindCursor<'a>

pub fn new(context: &UnwindContext<'a>) -> Result<Self, UnwindError>

Initializes a cursor for local unwinding using the state captured by the given UnwindContext.

pub fn step(&mut self) -> Result<bool, UnwindError>

Advances to the next (older) frame of the call chain.

Returns true if was another frame to step to or false if the cursor has reached the end.

Errors

This function may return one of the following errors:

• UnwindError::Unspecified if an unspecified error occurred
• UnwindError::NoInfo if libunwind was unable to locate the required unwind info
• UnwindError::BadVersion if the unwind info has an unsupported version or format
• UnwindError::InvalidIP if the instruction pointer of the next frame is invalid
• UnwindError::BadFrame if the next frame is invalid

pub fn register(&self, register: unw_regnum_t) -> Result<usize, UnwindError>

Retrieves the value of the given register for the cursor’s current frame.

Errors

This function may return one of the following errors:

• UnwindError::Unspecified if an unspecified error occurred
• UnwindError::BadRegister if the register was invalid or inaccessible in the current frame

pub unsafe fn set_register( &self, register: unw_regnum_t, value: unw_word_t, ) -> Result<(), UnwindError>

Sets the value of the given register in the cursor’s current frame to the given value.

Safety

The caller must ensure that updating the stack frame as described above will not cause undefined behavior.

Errors

This function may return one of the following errors:

• UnwindError::Unspecified if an unspecified error occurred
• UnwindError::BadRegister if the register was invalid or inaccessible in the current frame
• UnwindError::WriteToReadOnlyRegister if the register was read-only

pub fn fp_register(&self, register: unw_regnum_t) -> Result<usize, UnwindError>

Retrieves the value of the given floating point register for the cursor’s current frame.

Errors

This function may return one of the following errors:

• UnwindError::Unspecified if an unspecified error occurred
• UnwindError::BadRegister if the register was invalid or inaccessible in the current frame

pub unsafe fn set_fp_register( &self, register: unw_regnum_t, value: unw_fpreg_t, ) -> Result<(), UnwindError>

Sets the value of the given floating-point register in the cursor’s current frame to the given value.

Safety

The caller must ensure that updating the stack frame as described above will not cause undefined behavior.

Errors

This function may return one of the following errors:

• UnwindError::Unspecified if an unspecified error occurred
• UnwindError::BadRegister if the register was invalid or inaccessible in the current frame
• UnwindError::WriteToReadOnlyRegister if the register was read-only

pub fn is_fp_register(&self, register: unw_regnum_t) -> bool

Checks whether the given register is a floating-point register.

pub fn is_signal_frame(&self) -> Result<bool, UnwindError>

Checks whether the current frame is a “signal frame,” which is defined as a frame created in response to a potentially asynchronous interruption such as a device interrupt.

Signal frames offer access to a larger range of registers because their nature requires saving the contents of registers normally treated as “scratch” registers.

Corresponds to unw_is_signal_frame.

Errors

If libunwind is unable to determine whether the cursor is pointing to a signal frame, UnwindError::NoInfo is returned.

pub fn register_name(&self, register: unw_regnum_t) -> Option<&'static CStr>

Returns the name of the given register as a string, or [None] if the register does not exist.

pub const unsafe fn from_raw(raw: unw_cursor_t) -> Self

Creates a new UnwindCursor from a raw cursor acquired through FFI.

Safety

The returned cursor must be dropped before the stack frame it points at is destroyed.

Trait Implementations

impl<'a> Clone for UnwindCursor<'a>

fn clone(&self) -> UnwindCursor<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for UnwindCursor<'_>

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

Formats the value using the given formatter.