[][src]Module sgx_tstd::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.

Note: this module is unstable and is designed in RFC 2504, and you can learn more about its status in the tracking issue.

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 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!

Structs

Backtrace

A captured OS thread stack backtrace.

Enums

BacktraceStatus

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

PrintFormat

Controls how the backtrace should be formatted.

Functions

__rust_begin_short_backtrace

Fixed frame used to clean the backtrace with RUST_BACKTRACE=1. Note that this is only inline(never) when backtraces in libstd are enabled, otherwise it's fine to optimize away.

enable_backtrace

Enable backtrace for dumping call stack on crash.