Module std::backtrace_rs

source ·
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"

Next:

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

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!

Re-exports

Modules

Structs