Crate backtrace[−][src]
A library for acquiring a backtrace at runtime
This library is meant to supplement the RUST_BACKTRACE=1
support of the
standard library by allowing an acquisition of a backtrace at runtime
programmatically. The backtraces generated by this library do not need to be
parsed, for example, and expose the functionality of multiple backend
implementations.
Implementation
This library makes use of a number of strategies for actually acquiring a backtrace. For example unix uses libgcc’s libunwind bindings by default to acquire a backtrace, but coresymbolication or dladdr is used on OSX to acquire symbol names while linux uses gcc’s libbacktrace.
When using the default feature set of this library the “most reasonable” set of defaults is chosen for the current platform, but the features activated can also be controlled at a finer granularity.
API Principles
This library attempts to be as flexible as possible to accommodate different backend implementations of acquiring a backtrace. Consequently the currently exported functions are closure-based as opposed to the likely expected iterator-based versions. This is done due to limitations of the underlying APIs used from the system.
Usage
First, add this to your Cargo.toml
[dependencies]
backtrace = "0.3"
Next:
extern crate backtrace; fn main() { backtrace::trace(|frame| { let ip = frame.ip(); let symbol_address = frame.symbol_address(); // Resolve this instruction pointer to a symbol name backtrace::resolve_frame(frame, |symbol| { if let Some(name) = symbol.name() { // ... } if let Some(filename) = symbol.filename() { // ... } }); true // keep going to the next frame }); }
Structs
Backtrace | Representation of an owned and self-contained backtrace. |
BacktraceFmt | A formatter for backtraces. |
BacktraceFrame | Captured version of a frame in a backtrace. |
BacktraceFrameFmt | A formatter for just one frame of a backtrace. |
BacktraceSymbol | Captured version of a symbol in a backtrace. |
Frame | A trait representing one frame of a backtrace, yielded to the |
Symbol | A trait representing the resolution of a symbol in a file. |
SymbolName | A wrapper around a symbol name to provide ergonomic accessors to the demangled name, the raw bytes, the raw string, etc. |
Enums
BytesOrWideString | A platform independent representation of a string. When working with |
PrintFmt | The styles of printing that we can print |
Functions
clear_symbol_cache | Attempt to reclaim that cached memory used to symbolicate addresses. |
resolve | Resolve an address to a symbol, passing the symbol to the specified closure. |
resolve_frame | Resolve a previously capture frame to a symbol, passing the symbol to the specified closure. |
resolve_frame_unsynchronized⚠ | Same as |
resolve_unsynchronized⚠ | Same as |
trace | Inspects the current call-stack, passing all active frames into the closure provided to calculate a stack trace. |
trace_unsynchronized⚠ | Same as |