Support for capturing a stack backtrace of an OS thread

This module contains the support necessary to capture a stack backtrace of arunning OS thread from the OS thread itself. TheBacktrace type supportscapturing a stack trace via theBacktrace::capture andBacktrace::force_capture functions.

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

§Accuracy

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

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

§Platform support

Not all platforms that std compiles for support capturing backtraces. Someplatforms simply do nothing when capturing a backtrace. To check whether theplatform supports capturing backtraces you can consult theBacktraceStatusenum as a result ofBacktrace::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 gowrong which would cause a backtrace to not be captured. Please feel free toreport issues with platforms where a backtrace cannot be captured though!

§Environment Variables

TheBacktrace::capture function might not actually capture a backtrace bydefault. Its behavior is governed by two environment variables:

• RUST_LIB_BACKTRACE - if this is set to0 thenBacktrace::capturewill never capture a backtrace. Any other value set will enableBacktrace::capture.

• RUST_BACKTRACE - ifRUST_LIB_BACKTRACE is not set, then this variableis consulted with the same rules ofRUST_LIB_BACKTRACE.

• If neither of the above env vars are set, thenBacktrace::capture willbe disabled.

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

Note that theBacktrace::force_capture function can be used to ignorethese environment variables. Also note that the state of environmentvariables is cached once the first backtrace is created, so alteringRUST_LIB_BACKTRACE orRUST_BACKTRACE at runtime might not actually changehow backtraces are captured.