1 //! Support for capturing a stack backtrace of an OS thread
3 //! This module contains the support necessary to capture a stack backtrace of a
4 //! running OS thread from the OS thread itself. The `Backtrace` type supports
5 //! capturing a stack trace via the `Backtrace::capture` and
6 //! `Backtrace::force_capture` functions.
8 //! A backtrace is typically quite handy to attach to errors (e.g. types
9 //! implementing `std::error::Error`) to get a causal chain of where an error
12 //! > **Note**: this module is unstable and is designed in [RFC 2504], and you
13 //! > can learn more about its status in the [tracking issue].
15 //! [RFC 2504]: https://github.com/rust-lang/rfcs/blob/master/text/2504-fix-error.md
16 //! [tracking issue]: https://github.com/rust-lang/rust/issues/53487
20 //! Backtraces are attempted to be as accurate as possible, but no guarantees
21 //! are provided about the exact accuracy of a backtrace. Instruction pointers,
22 //! symbol names, filenames, line numbers, etc, may all be incorrect when
23 //! reported. Accuracy is attempted on a best-effort basis, however, and bugs
24 //! are always welcome to indicate areas of improvement!
26 //! For most platforms a backtrace with a filename/line number requires that
27 //! programs be compiled with debug information. Without debug information
28 //! filenames/line numbers will not be reported.
30 //! ## Platform support
32 //! Not all platforms that libstd compiles for support capturing backtraces.
33 //! Some platforms simply do nothing when capturing a backtrace. To check
34 //! whether the platform supports capturing backtraces you can consult the
35 //! `BacktraceStatus` enum as a result of `Backtrace::status`.
37 //! Like above with accuracy platform support is done on a best effort basis.
38 //! Sometimes libraries may not be available at runtime or something may go
39 //! wrong which would cause a backtrace to not be captured. Please feel free to
40 //! report issues with platforms where a backtrace cannot be captured though!
42 //! ## Environment Variables
44 //! The `Backtrace::capture` function may not actually capture a backtrace by
45 //! default. Its behavior is governed by two environment variables:
47 //! * `RUST_LIB_BACKTRACE` - if this is set to `0` then `Backtrace::capture`
48 //! will never capture a backtrace. Any other value this is set to will enable
49 //! `Backtrace::capture`.
51 //! * `RUST_BACKTRACE` - if `RUST_LIB_BACKTRACE` is not set, then this variable
52 //! is consulted with the same rules of `RUST_LIB_BACKTRACE`.
54 //! * If neither of the above env vars are set, then `Backtrace::capture` will
57 //! Capturing a backtrace can be a quite expensive runtime operation, so the
58 //! environment variables allow either forcibly disabling this runtime
59 //! performance hit or allow selectively enabling it in some programs.
61 //! Note that the `Backtrace::force_capture` function can be used to ignore
62 //! these environment variables. Also note that the state of environment
63 //! variables is cached once the first backtrace is created, so altering
64 //! `RUST_LIB_BACKTRACE` or `RUST_BACKTRACE` at runtime may not actually change
65 //! how backtraces are captured.
67 #![unstable(feature = "backtrace", issue = "53487")]
72 // NB: A note on resolution of a backtrace:
74 // Backtraces primarily happen in two steps, one is where we actually capture
75 // the stack backtrace, giving us a list of instruction pointers corresponding
76 // to stack frames. Next we take these instruction pointers and, one-by-one,
77 // turn them into a human readable name (like `main`).
79 // The first phase can be somewhat expensive (walking the stack), especially
80 // on MSVC where debug information is consulted to return inline frames each as
81 // their own frame. The second phase, however, is almost always extremely
82 // expensive (on the order of milliseconds sometimes) when it's consulting debug
85 // We attempt to amortize this cost as much as possible by delaying resolution
86 // of an address to a human readable name for as long as possible. When
87 // `Backtrace::create` is called to capture a backtrace it doesn't actually
88 // perform any symbol resolution, but rather we lazily resolve symbols only just
89 // before they're needed for printing. This way we can make capturing a
90 // backtrace and throwing it away much cheaper, but actually printing a
91 // backtrace is still basically the same cost.
93 // This strategy comes at the cost of some synchronization required inside of a
94 // `Backtrace`, but that's a relatively small price to pay relative to capturing
95 // a backtrace or actually symbolizing it.
97 use crate::backtrace_rs
::{self, BytesOrWideString}
;
99 use crate::ffi
::c_void
;
101 use crate::sync
::atomic
::{AtomicUsize, Ordering::SeqCst}
;
102 use crate::sync
::Mutex
;
103 use crate::sys_common
::backtrace
::{lock, output_filename}
;
106 /// A captured OS thread stack backtrace.
108 /// This type represents a stack backtrace for an OS thread captured at a
109 /// previous point in time. In some instances the `Backtrace` type may
110 /// internally be empty due to configuration. For more information see
111 /// `Backtrace::capture`.
112 pub struct Backtrace
{
116 /// The current status of a backtrace, indicating whether it was captured or
117 /// whether it is empty for some other reason.
119 #[derive(Debug, PartialEq, Eq)]
120 pub enum BacktraceStatus
{
121 /// Capturing a backtrace is not supported, likely because it's not
122 /// implemented for the current platform.
124 /// Capturing a backtrace has been disabled through either the
125 /// `RUST_LIB_BACKTRACE` or `RUST_BACKTRACE` environment variables.
127 /// A backtrace has been captured and the `Backtrace` should print
128 /// reasonable information when rendered.
135 Captured(Mutex
<Capture
>),
141 frames
: Vec
<BacktraceFrame
>,
144 fn _assert_send_sync() {
145 fn _assert
<T
: Send
+ Sync
>() {}
146 _assert
::<Backtrace
>();
149 struct BacktraceFrame
{
151 symbols
: Vec
<BacktraceSymbol
>,
155 Actual(backtrace_rs
::Frame
),
160 struct BacktraceSymbol
{
161 name
: Option
<Vec
<u8>>,
162 filename
: Option
<BytesOrWide
>,
171 impl fmt
::Debug
for Backtrace
{
172 fn fmt(&self, fmt
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
173 let mut capture
= match &self.inner
{
174 Inner
::Unsupported
=> return fmt
.write_str("<unsupported>"),
175 Inner
::Disabled
=> return fmt
.write_str("<disabled>"),
176 Inner
::Captured(c
) => c
.lock().unwrap(),
180 let frames
= &capture
.frames
[capture
.actual_start
..];
182 write
!(fmt
, "Backtrace ")?
;
184 let mut dbg
= fmt
.debug_list();
186 for frame
in frames
{
187 if frame
.frame
.ip().is_null() {
191 dbg
.entries(&frame
.symbols
);
198 impl fmt
::Debug
for BacktraceSymbol
{
199 fn fmt(&self, fmt
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
202 if let Some(fn_name
) = self.name
.as_ref().map(|b
| backtrace_rs
::SymbolName
::new(b
)) {
203 write
!(fmt
, "fn: \"{:#}\"", fn_name
)?
;
205 write
!(fmt
, "fn: <unknown>")?
;
208 if let Some(fname
) = self.filename
.as_ref() {
209 write
!(fmt
, ", file: \"{:?}\"", fname
)?
;
212 if let Some(line
) = self.lineno
.as_ref() {
213 write
!(fmt
, ", line: {:?}", line
)?
;
220 impl fmt
::Debug
for BytesOrWide
{
221 fn fmt(&self, fmt
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
225 BytesOrWide
::Bytes(w
) => BytesOrWideString
::Bytes(w
),
226 BytesOrWide
::Wide(w
) => BytesOrWideString
::Wide(w
),
228 backtrace_rs
::PrintFmt
::Short
,
229 crate::env
::current_dir().as_ref().ok(),
235 /// Returns whether backtrace captures are enabled through environment
237 fn enabled() -> bool
{
238 // Cache the result of reading the environment variables to make
239 // backtrace captures speedy, because otherwise reading environment
240 // variables every time can be somewhat slow.
241 static ENABLED
: AtomicUsize
= AtomicUsize
::new(0);
242 match ENABLED
.load(SeqCst
) {
247 let enabled
= match env
::var("RUST_LIB_BACKTRACE") {
249 Err(_
) => match env
::var("RUST_BACKTRACE") {
254 ENABLED
.store(enabled
as usize + 1, SeqCst
);
258 /// Capture a stack backtrace of the current thread.
260 /// This function will capture a stack backtrace of the current OS thread of
261 /// execution, returning a `Backtrace` type which can be later used to print
262 /// the entire stack trace or render it to a string.
264 /// This function will be a noop if the `RUST_BACKTRACE` or
265 /// `RUST_LIB_BACKTRACE` backtrace variables are both not set. If either
266 /// environment variable is set and enabled then this function will actually
267 /// capture a backtrace. Capturing a backtrace can be both memory intensive
268 /// and slow, so these environment variables allow liberally using
269 /// `Backtrace::capture` and only incurring a slowdown when the environment
270 /// variables are set.
272 /// To forcibly capture a backtrace regardless of environment variables, use
273 /// the `Backtrace::force_capture` function.
274 #[inline(never)] // want to make sure there's a frame here to remove
275 pub fn capture() -> Backtrace
{
276 if !Backtrace
::enabled() {
277 return Backtrace { inner: Inner::Disabled }
;
279 Backtrace
::create(Backtrace
::capture
as usize)
282 /// Forcibly captures a full backtrace, regardless of environment variable
285 /// This function behaves the same as `capture` except that it ignores the
286 /// values of the `RUST_BACKTRACE` and `RUST_LIB_BACKTRACE` environment
287 /// variables, always capturing a backtrace.
289 /// Note that capturing a backtrace can be an expensive operation on some
290 /// platforms, so this should be used with caution in performance-sensitive
292 #[inline(never)] // want to make sure there's a frame here to remove
293 pub fn force_capture() -> Backtrace
{
294 Backtrace
::create(Backtrace
::force_capture
as usize)
297 /// Forcibly captures a disabled backtrace, regardless of environment
298 /// variable configuration.
299 pub const fn disabled() -> Backtrace
{
300 Backtrace { inner: Inner::Disabled }
303 // Capture a backtrace which start just before the function addressed by
305 fn create(ip
: usize) -> Backtrace
{
307 let mut frames
= Vec
::new();
308 let mut actual_start
= None
;
310 backtrace_rs
::trace_unsynchronized(|frame
| {
311 frames
.push(BacktraceFrame
{
312 frame
: RawFrame
::Actual(frame
.clone()),
315 if frame
.symbol_address() as usize == ip
&& actual_start
.is_none() {
316 actual_start
= Some(frames
.len());
322 // If no frames came out assume that this is an unsupported platform
323 // since `backtrace` doesn't provide a way of learning this right now,
324 // and this should be a good enough approximation.
325 let inner
= if frames
.is_empty() {
328 Inner
::Captured(Mutex
::new(Capture
{
329 actual_start
: actual_start
.unwrap_or(0),
338 /// Returns the status of this backtrace, indicating whether this backtrace
339 /// request was unsupported, disabled, or a stack trace was actually
341 pub fn status(&self) -> BacktraceStatus
{
343 Inner
::Unsupported
=> BacktraceStatus
::Unsupported
,
344 Inner
::Disabled
=> BacktraceStatus
::Disabled
,
345 Inner
::Captured(_
) => BacktraceStatus
::Captured
,
350 impl fmt
::Display
for Backtrace
{
351 fn fmt(&self, fmt
: &mut fmt
::Formatter
<'_
>) -> fmt
::Result
{
352 let mut capture
= match &self.inner
{
353 Inner
::Unsupported
=> return fmt
.write_str("unsupported backtrace"),
354 Inner
::Disabled
=> return fmt
.write_str("disabled backtrace"),
355 Inner
::Captured(c
) => c
.lock().unwrap(),
359 let full
= fmt
.alternate();
360 let (frames
, style
) = if full
{
361 (&capture
.frames
[..], backtrace_rs
::PrintFmt
::Full
)
363 (&capture
.frames
[capture
.actual_start
..], backtrace_rs
::PrintFmt
::Short
)
366 // When printing paths we try to strip the cwd if it exists, otherwise
367 // we just print the path as-is. Note that we also only do this for the
368 // short format, because if it's full we presumably want to print
370 let cwd
= crate::env
::current_dir();
371 let mut print_path
= move |fmt
: &mut fmt
::Formatter
<'_
>, path
: BytesOrWideString
<'_
>| {
372 output_filename(fmt
, path
, style
, cwd
.as_ref().ok())
375 let mut f
= backtrace_rs
::BacktraceFmt
::new(fmt
, style
, &mut print_path
);
377 for frame
in frames
{
378 let mut f
= f
.frame();
379 if frame
.symbols
.is_empty() {
380 f
.print_raw(frame
.frame
.ip(), None
, None
, None
)?
;
382 for symbol
in frame
.symbols
.iter() {
385 symbol
.name
.as_ref().map(|b
| backtrace_rs
::SymbolName
::new(b
)),
386 symbol
.filename
.as_ref().map(|b
| match b
{
387 BytesOrWide
::Bytes(w
) => BytesOrWideString
::Bytes(w
),
388 BytesOrWide
::Wide(w
) => BytesOrWideString
::Wide(w
),
401 fn resolve(&mut self) {
402 // If we're already resolved, nothing to do!
406 self.resolved
= true;
408 // Use the global backtrace lock to synchronize this as it's a
409 // requirement of the `backtrace` crate, and then actually resolve
412 for frame
in self.frames
.iter_mut() {
413 let symbols
= &mut frame
.symbols
;
414 let frame
= match &frame
.frame
{
415 RawFrame
::Actual(frame
) => frame
,
417 RawFrame
::Fake
=> unimplemented
!(),
420 backtrace_rs
::resolve_frame_unsynchronized(frame
, |symbol
| {
421 symbols
.push(BacktraceSymbol
{
422 name
: symbol
.name().map(|m
| m
.as_bytes().to_vec()),
423 filename
: symbol
.filename_raw().map(|b
| match b
{
424 BytesOrWideString
::Bytes(b
) => BytesOrWide
::Bytes(b
.to_owned()),
425 BytesOrWideString
::Wide(b
) => BytesOrWide
::Wide(b
.to_owned()),
427 lineno
: symbol
.lineno(),
436 fn ip(&self) -> *mut c_void
{
438 RawFrame
::Actual(frame
) => frame
.ip(),
440 RawFrame
::Fake
=> 1 as *mut c_void
,