Module no_std_compat::backtrace

Support for capturing a stack backtrace of an OS thread

This module contains the support necessary to capture a stack backtrace of a running OS thread from the OS thread itself. The Backtrace type supports capturing a stack trace via the Backtrace::capture and Backtrace::force_capture functions.

A backtrace is typically quite handy to attach to errors (e.g. types implementing std::error::Error) to get a causal chain of where an error was generated.

Accuracy

Backtraces are attempted to be as accurate as possible, but no guarantees are provided about the exact accuracy of a backtrace. Instruction pointers, symbol names, filenames, line numbers, etc, may all be incorrect when reported. Accuracy is attempted on a best-effort basis, however, any bug reports are always welcome to indicate areas of improvement!

For most platforms a backtrace with a filename/line number requires that programs be compiled with debug information. Without debug information filenames/line numbers will not be reported.

Platform support

Not all platforms that std compiles for support capturing backtraces. Some platforms simply do nothing when capturing a backtrace. To check whether the platform supports capturing backtraces you can consult the BacktraceStatus enum as a result of Backtrace::status.

Like above with accuracy platform support is done on a best effort basis. Sometimes libraries might not be available at runtime or something may go wrong which would cause a backtrace to not be captured. Please feel free to report issues with platforms where a backtrace cannot be captured though!

Environment Variables

The Backtrace::capture function might not actually capture a backtrace by default. Its behavior is governed by two environment variables:

• RUST_LIB_BACKTRACE - if this is set to 0 then Backtrace::capture will never capture a backtrace. Any other value set will enable Backtrace::capture.

• RUST_BACKTRACE - if RUST_LIB_BACKTRACE is not set, then this variable is consulted with the same rules of RUST_LIB_BACKTRACE.

• If neither of the above env vars are set, then Backtrace::capture will be disabled.

Capturing a backtrace can be a quite expensive runtime operation, so the environment variables allow either forcibly disabling this runtime performance hit or allow selectively enabling it in some programs.

Note that the Backtrace::force_capture function can be used to ignore these environment variables. Also note that the state of environment variables is cached once the first backtrace is created, so altering RUST_LIB_BACKTRACE or RUST_BACKTRACE at runtime might not actually change how backtraces are captured.

Structs

• Backtrace
  A captured OS thread stack backtrace.
• BacktraceFrameExperimental
  A single frame of a backtrace.

Enums

• BacktraceStatus
  The current status of a backtrace, indicating whether it was captured or whether it is empty for some other reason.