Expand description
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, 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.
Platform support
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 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 to0thenBacktrace::capturewill never capture a backtrace. Any other value this is set to will enableBacktrace::capture. -
RUST_BACKTRACE- ifRUST_LIB_BACKTRACEis not set, then this variable is consulted with the same rules ofRUST_LIB_BACKTRACE. -
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_LIB_BACKTRACE or RUST_BACKTRACE at runtime might not actually change
how backtraces are captured.