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
A backtrace is typically quite handy to attach to errors (e.g. types
std::error::Error) to get a causal chain of where an error
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, and bugs 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.
Not all platforms that libstd 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
Like above with accuracy platform support is done on a best effort basis. Sometimes libraries may 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!
Backtrace::capture function may not actually capture a backtrace by
default. Its behavior is governed by two environment variables:
RUST_LIB_BACKTRACE- if this is set to
Backtrace::capturewill never capture a backtrace. Any other value this is set to will enable
RUST_LIB_BACKTRACEis not set, then this variable is consulted with the same rules of
If neither of the above env vars are set, then
Backtrace::capturewill 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_BACKTRACE at runtime may not actually change
how backtraces are captured.
A captured OS thread stack backtrace.
The current status of a backtrace, indicating whether it was captured or whether it is empty for some other reason.