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
14 //! Backtraces are attempted to be as accurate as possible, but no guarantees
15 //! are provided about the exact accuracy of a backtrace. Instruction pointers,
16 //! symbol names, filenames, line numbers, etc, may all be incorrect when
17 //! reported. Accuracy is attempted on a best-effort basis, however, and bugs
18 //! are always welcome to indicate areas of improvement!
20 //! For most platforms a backtrace with a filename/line number requires that
21 //! programs be compiled with debug information. Without debug information
22 //! filenames/line numbers will not be reported.
24 //! ## Platform support
26 //! Not all platforms that libstd compiles for support capturing backtraces.
27 //! Some platforms simply do nothing when capturing a backtrace. To check
28 //! whether the platform supports capturing backtraces you can consult the
29 //! `BacktraceStatus` enum as a result of `Backtrace::status`.
31 //! Like above with accuracy platform support is done on a best effort basis.
32 //! Sometimes libraries might not be available at runtime or something may go
33 //! wrong which would cause a backtrace to not be captured. Please feel free to
34 //! report issues with platforms where a backtrace cannot be captured though!
36 //! ## Environment Variables
38 //! The `Backtrace::capture` function might not actually capture a backtrace by
39 //! default. Its behavior is governed by two environment variables:
41 //! * `RUST_LIB_BACKTRACE` - if this is set to `0` then `Backtrace::capture`
42 //! will never capture a backtrace. Any other value this is set to will enable
43 //! `Backtrace::capture`.
45 //! * `RUST_BACKTRACE` - if `RUST_LIB_BACKTRACE` is not set, then this variable
46 //! is consulted with the same rules of `RUST_LIB_BACKTRACE`.
48 //! * If neither of the above env vars are set, then `Backtrace::capture` will
51 //! Capturing a backtrace can be a quite expensive runtime operation, so the
52 //! environment variables allow either forcibly disabling this runtime
53 //! performance hit or allow selectively enabling it in some programs.
55 //! Note that the `Backtrace::force_capture` function can be used to ignore
56 //! these environment variables. Also note that the state of environment
57 //! variables is cached once the first backtrace is created, so altering
58 //! `RUST_LIB_BACKTRACE` or `RUST_BACKTRACE` at runtime might not actually change
59 //! how backtraces are captured.
61 #![stable(feature = "backtrace", since = "1.65.0")]
66 // NB: A note on resolution of a backtrace:
68 // Backtraces primarily happen in two steps, one is where we actually capture
69 // the stack backtrace, giving us a list of instruction pointers corresponding
70 // to stack frames. Next we take these instruction pointers and, one-by-one,
71 // turn them into a human readable name (like `main`).
73 // The first phase can be somewhat expensive (walking the stack), especially
74 // on MSVC where debug information is consulted to return inline frames each as
75 // their own frame. The second phase, however, is almost always extremely
76 // expensive (on the order of milliseconds sometimes) when it's consulting debug
79 // We attempt to amortize this cost as much as possible by delaying resolution
80 // of an address to a human readable name for as long as possible. When
81 // `Backtrace::create` is called to capture a backtrace it doesn't actually
82 // perform any symbol resolution, but rather we lazily resolve symbols only just
83 // before they're needed for printing. This way we can make capturing a
84 // backtrace and throwing it away much cheaper, but actually printing a
85 // backtrace is still basically the same cost.
87 // This strategy comes at the cost of some synchronization required inside of a
88 // `Backtrace`, but that's a relatively small price to pay relative to capturing
89 // a backtrace or actually symbolizing it.
91 use crate::backtrace_rs::{self, BytesOrWideString};
92 use crate::cell::UnsafeCell;
94 use crate::ffi::c_void;
96 use crate::sync::atomic::{AtomicUsize, Ordering::Relaxed};
97 use crate::sync::Once;
98 use crate::sys_common::backtrace::{lock, output_filename};
101 /// A captured OS thread stack backtrace.
103 /// This type represents a stack backtrace for an OS thread captured at a
104 /// previous point in time. In some instances the `Backtrace` type may
105 /// internally be empty due to configuration. For more information see
106 /// `Backtrace::capture`.
107 #[stable(feature = "backtrace", since = "1.65.0")]
109 pub struct Backtrace {
113 /// The current status of a backtrace, indicating whether it was captured or
114 /// whether it is empty for some other reason.
115 #[stable(feature = "backtrace", since = "1.65.0")]
117 #[derive(Debug, PartialEq, Eq)]
118 pub enum BacktraceStatus {
119 /// Capturing a backtrace is not supported, likely because it's not
120 /// implemented for the current platform.
122 /// Capturing a backtrace has been disabled through either the
123 /// `RUST_LIB_BACKTRACE` or `RUST_BACKTRACE` environment variables.
125 /// A backtrace has been captured and the `Backtrace` should print
126 /// reasonable information when rendered.
133 Captured(LazilyResolvedCapture),
139 frames: Vec<BacktraceFrame>,
142 fn _assert_send_sync() {
143 fn _assert<T: Send + Sync>() {}
144 _assert::<Backtrace>();
147 /// A single frame of a backtrace.
148 #[unstable(feature = "backtrace_frames", issue = "79676")]
149 pub struct BacktraceFrame {
151 symbols: Vec<BacktraceSymbol>,
156 Actual(backtrace_rs::Frame),
161 struct BacktraceSymbol {
162 name: Option<Vec<u8>>,
163 filename: Option<BytesOrWide>,
173 #[stable(feature = "backtrace", since = "1.65.0")]
174 impl fmt::Debug for Backtrace {
175 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
176 let capture = match &self.inner {
177 Inner::Unsupported => return fmt.write_str("<unsupported>"),
178 Inner::Disabled => return fmt.write_str("<disabled>"),
179 Inner::Captured(c) => c.force(),
182 let frames = &capture.frames[capture.actual_start..];
184 write!(fmt, "Backtrace ")?;
186 let mut dbg = fmt.debug_list();
188 for frame in frames {
189 if frame.frame.ip().is_null() {
193 dbg.entries(&frame.symbols);
200 #[unstable(feature = "backtrace_frames", issue = "79676")]
201 impl fmt::Debug for BacktraceFrame {
202 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
203 let mut dbg = fmt.debug_list();
204 dbg.entries(&self.symbols);
209 impl fmt::Debug for BacktraceSymbol {
210 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
211 // FIXME: improve formatting: https://github.com/rust-lang/rust/issues/65280
212 // FIXME: Also, include column numbers into the debug format as Display already has them.
213 // Until there are stable per-frame accessors, the format shouldn't be changed:
214 // https://github.com/rust-lang/rust/issues/65280#issuecomment-638966585
217 if let Some(fn_name) = self.name.as_ref().map(|b| backtrace_rs::SymbolName::new(b)) {
218 write!(fmt, "fn: \"{:#}\"", fn_name)?;
220 write!(fmt, "fn: <unknown>")?;
223 if let Some(fname) = self.filename.as_ref() {
224 write!(fmt, ", file: \"{:?}\"", fname)?;
227 if let Some(line) = self.lineno {
228 write!(fmt, ", line: {:?}", line)?;
235 impl fmt::Debug for BytesOrWide {
236 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
240 BytesOrWide::Bytes(w) => BytesOrWideString::Bytes(w),
241 BytesOrWide::Wide(w) => BytesOrWideString::Wide(w),
243 backtrace_rs::PrintFmt::Short,
244 crate::env::current_dir().as_ref().ok(),
250 /// Returns whether backtrace captures are enabled through environment
252 fn enabled() -> bool {
253 // Cache the result of reading the environment variables to make
254 // backtrace captures speedy, because otherwise reading environment
255 // variables every time can be somewhat slow.
256 static ENABLED: AtomicUsize = AtomicUsize::new(0);
257 match ENABLED.load(Relaxed) {
262 let enabled = match env::var("RUST_LIB_BACKTRACE") {
264 Err(_) => match env::var("RUST_BACKTRACE") {
269 ENABLED.store(enabled as usize + 1, Relaxed);
273 /// Capture a stack backtrace of the current thread.
275 /// This function will capture a stack backtrace of the current OS thread of
276 /// execution, returning a `Backtrace` type which can be later used to print
277 /// the entire stack trace or render it to a string.
279 /// This function will be a noop if the `RUST_BACKTRACE` or
280 /// `RUST_LIB_BACKTRACE` backtrace variables are both not set. If either
281 /// environment variable is set and enabled then this function will actually
282 /// capture a backtrace. Capturing a backtrace can be both memory intensive
283 /// and slow, so these environment variables allow liberally using
284 /// `Backtrace::capture` and only incurring a slowdown when the environment
285 /// variables are set.
287 /// To forcibly capture a backtrace regardless of environment variables, use
288 /// the `Backtrace::force_capture` function.
289 #[stable(feature = "backtrace", since = "1.65.0")]
290 #[inline(never)] // want to make sure there's a frame here to remove
291 pub fn capture() -> Backtrace {
292 if !Backtrace::enabled() {
293 return Backtrace { inner: Inner::Disabled };
295 Backtrace::create(Backtrace::capture as usize)
298 /// Forcibly captures a full backtrace, regardless of environment variable
301 /// This function behaves the same as `capture` except that it ignores the
302 /// values of the `RUST_BACKTRACE` and `RUST_LIB_BACKTRACE` environment
303 /// variables, always capturing a backtrace.
305 /// Note that capturing a backtrace can be an expensive operation on some
306 /// platforms, so this should be used with caution in performance-sensitive
308 #[stable(feature = "backtrace", since = "1.65.0")]
309 #[inline(never)] // want to make sure there's a frame here to remove
310 pub fn force_capture() -> Backtrace {
311 Backtrace::create(Backtrace::force_capture as usize)
314 /// Forcibly captures a disabled backtrace, regardless of environment
315 /// variable configuration.
316 #[stable(feature = "backtrace", since = "1.65.0")]
317 #[rustc_const_stable(feature = "backtrace", since = "1.65.0")]
318 pub const fn disabled() -> Backtrace {
319 Backtrace { inner: Inner::Disabled }
322 // Capture a backtrace which start just before the function addressed by
324 fn create(ip: usize) -> Backtrace {
325 // SAFETY: We don't attempt to lock this reentrantly.
326 let _lock = unsafe { lock() };
327 let mut frames = Vec::new();
328 let mut actual_start = None;
330 backtrace_rs::trace_unsynchronized(|frame| {
331 frames.push(BacktraceFrame {
332 frame: RawFrame::Actual(frame.clone()),
335 if frame.symbol_address().addr() == ip && actual_start.is_none() {
336 actual_start = Some(frames.len());
342 // If no frames came out assume that this is an unsupported platform
343 // since `backtrace` doesn't provide a way of learning this right now,
344 // and this should be a good enough approximation.
345 let inner = if frames.is_empty() {
348 Inner::Captured(LazilyResolvedCapture::new(Capture {
349 actual_start: actual_start.unwrap_or(0),
358 /// Returns the status of this backtrace, indicating whether this backtrace
359 /// request was unsupported, disabled, or a stack trace was actually
361 #[stable(feature = "backtrace", since = "1.65.0")]
363 pub fn status(&self) -> BacktraceStatus {
365 Inner::Unsupported => BacktraceStatus::Unsupported,
366 Inner::Disabled => BacktraceStatus::Disabled,
367 Inner::Captured(_) => BacktraceStatus::Captured,
373 /// Returns an iterator over the backtrace frames.
375 #[unstable(feature = "backtrace_frames", issue = "79676")]
376 pub fn frames(&'a self) -> &'a [BacktraceFrame] {
377 if let Inner::Captured(c) = &self.inner { &c.force().frames } else { &[] }
381 #[stable(feature = "backtrace", since = "1.65.0")]
382 impl fmt::Display for Backtrace {
383 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
384 let capture = match &self.inner {
385 Inner::Unsupported => return fmt.write_str("unsupported backtrace"),
386 Inner::Disabled => return fmt.write_str("disabled backtrace"),
387 Inner::Captured(c) => c.force(),
390 let full = fmt.alternate();
391 let (frames, style) = if full {
392 (&capture.frames[..], backtrace_rs::PrintFmt::Full)
394 (&capture.frames[capture.actual_start..], backtrace_rs::PrintFmt::Short)
397 // When printing paths we try to strip the cwd if it exists, otherwise
398 // we just print the path as-is. Note that we also only do this for the
399 // short format, because if it's full we presumably want to print
401 let cwd = crate::env::current_dir();
402 let mut print_path = move |fmt: &mut fmt::Formatter<'_>, path: BytesOrWideString<'_>| {
403 output_filename(fmt, path, style, cwd.as_ref().ok())
406 let mut f = backtrace_rs::BacktraceFmt::new(fmt, style, &mut print_path);
408 for frame in frames {
409 if frame.symbols.is_empty() {
410 f.frame().print_raw(frame.frame.ip(), None, None, None)?;
412 for symbol in frame.symbols.iter() {
413 f.frame().print_raw_with_column(
415 symbol.name.as_ref().map(|b| backtrace_rs::SymbolName::new(b)),
416 symbol.filename.as_ref().map(|b| match b {
417 BytesOrWide::Bytes(w) => BytesOrWideString::Bytes(w),
418 BytesOrWide::Wide(w) => BytesOrWideString::Wide(w),
431 struct LazilyResolvedCapture {
433 capture: UnsafeCell<Capture>,
436 impl LazilyResolvedCapture {
437 fn new(capture: Capture) -> Self {
438 LazilyResolvedCapture { sync: Once::new(), capture: UnsafeCell::new(capture) }
441 fn force(&self) -> &Capture {
442 self.sync.call_once(|| {
443 // SAFETY: This exclusive reference can't overlap with any others
444 // `Once` guarantees callers will block until this closure returns
445 // `Once` also guarantees only a single caller will enter this closure
446 unsafe { &mut *self.capture.get() }.resolve();
449 // SAFETY: This shared reference can't overlap with the exclusive reference above
450 unsafe { &*self.capture.get() }
454 // SAFETY: Access to the inner value is synchronized using a thread-safe `Once`
455 // So long as `Capture` is `Sync`, `LazilyResolvedCapture` is too
456 unsafe impl Sync for LazilyResolvedCapture where Capture: Sync {}
459 fn resolve(&mut self) {
460 // If we're already resolved, nothing to do!
464 self.resolved = true;
466 // Use the global backtrace lock to synchronize this as it's a
467 // requirement of the `backtrace` crate, and then actually resolve
469 // SAFETY: We don't attempt to lock this reentrantly.
470 let _lock = unsafe { lock() };
471 for frame in self.frames.iter_mut() {
472 let symbols = &mut frame.symbols;
473 let frame = match &frame.frame {
474 RawFrame::Actual(frame) => frame,
476 RawFrame::Fake => unimplemented!(),
479 backtrace_rs::resolve_frame_unsynchronized(frame, |symbol| {
480 symbols.push(BacktraceSymbol {
481 name: symbol.name().map(|m| m.as_bytes().to_vec()),
482 filename: symbol.filename_raw().map(|b| match b {
483 BytesOrWideString::Bytes(b) => BytesOrWide::Bytes(b.to_owned()),
484 BytesOrWideString::Wide(b) => BytesOrWide::Wide(b.to_owned()),
486 lineno: symbol.lineno(),
487 colno: symbol.colno(),
496 fn ip(&self) -> *mut c_void {
498 RawFrame::Actual(frame) => frame.ip(),
500 RawFrame::Fake => crate::ptr::invalid_mut(1),