Crate backtrace

Expand description

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.

Usage

First, add this to your Cargo.toml

[dependencies]
backtrace = "0.3"

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
    });
}

Backtrace accuracy

This crate implements best-effort attempts to get the native backtrace. This is not always guaranteed to work, and some platforms don’t return any backtrace at all. If your application requires accurate backtraces then it’s recommended to closely evaluate this crate to see whether it’s suitable for your use case on your target platforms.

Even on supported platforms, there’s a number of reasons that backtraces may be less-than-accurate, including but not limited to:

Unwind information may not be available. This crate primarily implements backtraces by unwinding the stack, but not all functions may have unwinding information (e.g. DWARF unwinding information).
Rust code may be compiled without unwinding information for some functions. This can also happen for Rust code compiled with -Cpanic=abort. You can remedy this, however, with -Cforce-unwind-tables as a compiler option.
Unwind information may be inaccurate or corrupt. In the worst case inaccurate unwind information can lead this library to segfault. In the best case inaccurate information will result in a truncated stack trace.
Backtraces may not report filenames/line numbers correctly due to missing or corrupt debug information. This won’t lead to segfaults unlike corrupt unwinding information, but missing or malformed debug information will mean that filenames and line numbers will not be available. This may be because debug information wasn’t generated by the compiler, or it’s just missing on the filesystem.
Not all platforms are supported. For example there’s no way to get a backtrace on WebAssembly at the moment.
Crate features may be disabled. Currently this crate supports using Gimli libbacktrace on non-Windows platforms for reading debuginfo for backtraces. If both crate features are disabled, however, then these platforms will generate a backtrace but be unable to generate symbols for it.

In most standard workflows for most standard platforms you generally don’t need to worry about these caveats. We’ll try to fix ones where we can over time, but otherwise it’s important to be aware of the limitations of unwinding-based backtraces!

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 trace function of this crate.
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 std enabled it is recommended to the convenience methods for providing conversions to std types.
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_frame, only unsafe as it’s unsynchronized.
resolve_unsynchronized^⚠
Same as resolve, only unsafe as it’s unsynchronized.
trace
Inspects the current call-stack, passing all active frames into the closure provided to calculate a stack trace.
trace_unsynchronized^⚠
Same as trace, only unsafe as it’s unsynchronized.