library/std/src/backtrace.rs

   1 //! Support for capturing a stack backtrace of an OS thread
   2 //!
   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.
   7 //!
   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
  10 //! was generated.
  11 //!
  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].
  14 //!
  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
  17 //!
  18 //! ## Accuracy
  19 //!
  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!
  25 //!
  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.
  29 //!
  30 //! ## Platform support
  31 //!
  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`.
  36 //!
  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!
  41 //!
  42 //! ## Environment Variables
  43 //!
  44 //! The `Backtrace::capture` function may not actually capture a backtrace by
  45 //! default. Its behavior is governed by two environment variables:
  46 //!
  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`.
  50 //!
  51 //! * `RUST_BACKTRACE` - if `RUST_LIB_BACKTRACE` is not set, then this variable
  52 //!   is consulted with the same rules of `RUST_LIB_BACKTRACE`.
  53 //!
  54 //! * If neither of the above env vars are set, then `Backtrace::capture` will
  55 //!   be disabled.
  56 //!
  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.
  60 //!
  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.
  66
  67 #![unstable(feature = "backtrace", issue = "53487")]
  68
  69 // NB: A note on resolution of a backtrace:
  70 //
  71 // Backtraces primarily happen in two steps, one is where we actually capture
  72 // the stack backtrace, giving us a list of instruction pointers corresponding
  73 // to stack frames. Next we take these instruction pointers and, one-by-one,
  74 // turn them into a human readable name (like `main`).
  75 //
  76 // The first phase can be somewhat expensive (walking the stack), especially
  77 // on MSVC where debug information is consulted to return inline frames each as
  78 // their own frame. The second phase, however, is almost always extremely
  79 // expensive (on the order of milliseconds sometimes) when it's consulting debug
  80 // information.
  81 //
  82 // We attempt to amortize this cost as much as possible by delaying resolution
  83 // of an address to a human readable name for as long as possible. When
  84 // `Backtrace::create` is called to capture a backtrace it doesn't actually
  85 // perform any symbol resolution, but rather we lazily resolve symbols only just
  86 // before they're needed for printing. This way we can make capturing a
  87 // backtrace and throwing it away much cheaper, but actually printing a
  88 // backtrace is still basically the same cost.
  89 //
  90 // This strategy comes at the cost of some synchronization required inside of a
  91 // `Backtrace`, but that's a relatively small price to pay relative to capturing
  92 // a backtrace or actually symbolizing it.
  93
  94 use crate::env;
  95 use crate::ffi::c_void;
  96 use crate::fmt;
  97 use crate::sync::atomic::{AtomicUsize, Ordering::SeqCst};
  98 use crate::sync::Mutex;
  99 use crate::sys_common::backtrace::{lock, output_filename};
 100 use crate::vec::Vec;
 101 use backtrace::BytesOrWideString;
 102 use backtrace_rs as backtrace;
 103
 104 /// A captured OS thread stack backtrace.
 105 ///
 106 /// This type represents a stack backtrace for an OS thread captured at a
 107 /// previous point in time. In some instances the `Backtrace` type may
 108 /// internally be empty due to configuration. For more information see
 109 /// `Backtrace::capture`.
 110 pub struct Backtrace {
 111     inner: Inner,
 112 }
 113
 114 /// The current status of a backtrace, indicating whether it was captured or
 115 /// whether it is empty for some other reason.
 116 #[non_exhaustive]
 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.
 121     Unsupported,
 122     /// Capturing a backtrace has been disabled through either the
 123     /// `RUST_LIB_BACKTRACE` or `RUST_BACKTRACE` environment variables.
 124     Disabled,
 125     /// A backtrace has been captured and the `Backtrace` should print
 126     /// reasonable information when rendered.
 127     Captured,
 128 }
 129
 130 enum Inner {
 131     Unsupported,
 132     Disabled,
 133     Captured(Mutex<Capture>),
 134 }
 135
 136 struct Capture {
 137     actual_start: usize,
 138     resolved: bool,
 139     frames: Vec<BacktraceFrame>,
 140 }
 141
 142 fn _assert_send_sync() {
 143     fn _assert<T: Send + Sync>() {}
 144     _assert::<Backtrace>();
 145 }
 146
 147 struct BacktraceFrame {
 148     frame: RawFrame,
 149     symbols: Vec<BacktraceSymbol>,
 150 }
 151
 152 enum RawFrame {
 153     Actual(backtrace::Frame),
 154     #[cfg(test)]
 155     Fake,
 156 }
 157
 158 struct BacktraceSymbol {
 159     name: Option<Vec<u8>>,
 160     filename: Option<BytesOrWide>,
 161     lineno: Option<u32>,
 162 }
 163
 164 enum BytesOrWide {
 165     Bytes(Vec<u8>),
 166     Wide(Vec<u16>),
 167 }
 168
 169 impl fmt::Debug for Backtrace {
 170     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
 171         let mut capture = match &self.inner {
 172             Inner::Unsupported => return fmt.write_str("<unsupported>"),
 173             Inner::Disabled => return fmt.write_str("<disabled>"),
 174             Inner::Captured(c) => c.lock().unwrap(),
 175         };
 176         capture.resolve();
 177
 178         let frames = &capture.frames[capture.actual_start..];
 179
 180         write!(fmt, "Backtrace ")?;
 181
 182         let mut dbg = fmt.debug_list();
 183
 184         for frame in frames {
 185             if frame.frame.ip().is_null() {
 186                 continue;
 187             }
 188
 189             dbg.entries(&frame.symbols);
 190         }
 191
 192         dbg.finish()
 193     }
 194 }
 195
 196 impl fmt::Debug for BacktraceSymbol {
 197     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
 198         write!(fmt, "{{ ")?;
 199
 200         if let Some(fn_name) = self.name.as_ref().map(|b| backtrace::SymbolName::new(b)) {
 201             write!(fmt, "fn: \"{:#}\"", fn_name)?;
 202         } else {
 203             write!(fmt, "fn: <unknown>")?;
 204         }
 205
 206         if let Some(fname) = self.filename.as_ref() {
 207             write!(fmt, ", file: \"{:?}\"", fname)?;
 208         }
 209
 210         if let Some(line) = self.lineno.as_ref() {
 211             write!(fmt, ", line: {:?}", line)?;
 212         }
 213
 214         write!(fmt, " }}")
 215     }
 216 }
 217
 218 impl fmt::Debug for BytesOrWide {
 219     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
 220         output_filename(
 221             fmt,
 222             match self {
 223                 BytesOrWide::Bytes(w) => BytesOrWideString::Bytes(w),
 224                 BytesOrWide::Wide(w) => BytesOrWideString::Wide(w),
 225             },
 226             backtrace::PrintFmt::Short,
 227             crate::env::current_dir().as_ref().ok(),
 228         )
 229     }
 230 }
 231
 232 impl Backtrace {
 233     /// Returns whether backtrace captures are enabled through environment
 234     /// variables.
 235     fn enabled() -> bool {
 236         // Cache the result of reading the environment variables to make
 237         // backtrace captures speedy, because otherwise reading environment
 238         // variables every time can be somewhat slow.
 239         static ENABLED: AtomicUsize = AtomicUsize::new(0);
 240         match ENABLED.load(SeqCst) {
 241             0 => {}
 242             1 => return false,
 243             _ => return true,
 244         }
 245         let enabled = match env::var("RUST_LIB_BACKTRACE") {
 246             Ok(s) => s != "0",
 247             Err(_) => match env::var("RUST_BACKTRACE") {
 248                 Ok(s) => s != "0",
 249                 Err(_) => false,
 250             },
 251         };
 252         ENABLED.store(enabled as usize + 1, SeqCst);
 253         enabled
 254     }
 255
 256     /// Capture a stack backtrace of the current thread.
 257     ///
 258     /// This function will capture a stack backtrace of the current OS thread of
 259     /// execution, returning a `Backtrace` type which can be later used to print
 260     /// the entire stack trace or render it to a string.
 261     ///
 262     /// This function will be a noop if the `RUST_BACKTRACE` or
 263     /// `RUST_LIB_BACKTRACE` backtrace variables are both not set. If either
 264     /// environment variable is set and enabled then this function will actually
 265     /// capture a backtrace. Capturing a backtrace can be both memory intensive
 266     /// and slow, so these environment variables allow liberally using
 267     /// `Backtrace::capture` and only incurring a slowdown when the environment
 268     /// variables are set.
 269     ///
 270     /// To forcibly capture a backtrace regardless of environment variables, use
 271     /// the `Backtrace::force_capture` function.
 272     #[inline(never)] // want to make sure there's a frame here to remove
 273     pub fn capture() -> Backtrace {
 274         if !Backtrace::enabled() {
 275             return Backtrace { inner: Inner::Disabled };
 276         }
 277         Backtrace::create(Backtrace::capture as usize)
 278     }
 279
 280     /// Forcibly captures a full backtrace, regardless of environment variable
 281     /// configuration.
 282     ///
 283     /// This function behaves the same as `capture` except that it ignores the
 284     /// values of the `RUST_BACKTRACE` and `RUST_LIB_BACKTRACE` environment
 285     /// variables, always capturing a backtrace.
 286     ///
 287     /// Note that capturing a backtrace can be an expensive operation on some
 288     /// platforms, so this should be used with caution in performance-sensitive
 289     /// parts of code.
 290     #[inline(never)] // want to make sure there's a frame here to remove
 291     pub fn force_capture() -> Backtrace {
 292         Backtrace::create(Backtrace::force_capture as usize)
 293     }
 294
 295     /// Forcibly captures a disabled backtrace, regardless of environment
 296     /// variable configuration.
 297     pub const fn disabled() -> Backtrace {
 298         Backtrace { inner: Inner::Disabled }
 299     }
 300
 301     // Capture a backtrace which start just before the function addressed by
 302     // `ip`
 303     fn create(ip: usize) -> Backtrace {
 304         let _lock = lock();
 305         let mut frames = Vec::new();
 306         let mut actual_start = None;
 307         unsafe {
 308             backtrace::trace_unsynchronized(|frame| {
 309                 frames.push(BacktraceFrame {
 310                     frame: RawFrame::Actual(frame.clone()),
 311                     symbols: Vec::new(),
 312                 });
 313                 if frame.symbol_address() as usize == ip && actual_start.is_none() {
 314                     actual_start = Some(frames.len());
 315                 }
 316                 true
 317             });
 318         }
 319
 320         // If no frames came out assume that this is an unsupported platform
 321         // since `backtrace` doesn't provide a way of learning this right now,
 322         // and this should be a good enough approximation.
 323         let inner = if frames.is_empty() {
 324             Inner::Unsupported
 325         } else {
 326             Inner::Captured(Mutex::new(Capture {
 327                 actual_start: actual_start.unwrap_or(0),
 328                 frames,
 329                 resolved: false,
 330             }))
 331         };
 332
 333         Backtrace { inner }
 334     }
 335
 336     /// Returns the status of this backtrace, indicating whether this backtrace
 337     /// request was unsupported, disabled, or a stack trace was actually
 338     /// captured.
 339     pub fn status(&self) -> BacktraceStatus {
 340         match self.inner {
 341             Inner::Unsupported => BacktraceStatus::Unsupported,
 342             Inner::Disabled => BacktraceStatus::Disabled,
 343             Inner::Captured(_) => BacktraceStatus::Captured,
 344         }
 345     }
 346 }
 347
 348 impl fmt::Display for Backtrace {
 349     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
 350         let mut capture = match &self.inner {
 351             Inner::Unsupported => return fmt.write_str("unsupported backtrace"),
 352             Inner::Disabled => return fmt.write_str("disabled backtrace"),
 353             Inner::Captured(c) => c.lock().unwrap(),
 354         };
 355         capture.resolve();
 356
 357         let full = fmt.alternate();
 358         let (frames, style) = if full {
 359             (&capture.frames[..], backtrace::PrintFmt::Full)
 360         } else {
 361             (&capture.frames[capture.actual_start..], backtrace::PrintFmt::Short)
 362         };
 363
 364         // When printing paths we try to strip the cwd if it exists, otherwise
 365         // we just print the path as-is. Note that we also only do this for the
 366         // short format, because if it's full we presumably want to print
 367         // everything.
 368         let cwd = crate::env::current_dir();
 369         let mut print_path = move |fmt: &mut fmt::Formatter<'_>, path: BytesOrWideString<'_>| {
 370             output_filename(fmt, path, style, cwd.as_ref().ok())
 371         };
 372
 373         let mut f = backtrace::BacktraceFmt::new(fmt, style, &mut print_path);
 374         f.add_context()?;
 375         for frame in frames {
 376             let mut f = f.frame();
 377             if frame.symbols.is_empty() {
 378                 f.print_raw(frame.frame.ip(), None, None, None)?;
 379             } else {
 380                 for symbol in frame.symbols.iter() {
 381                     f.print_raw(
 382                         frame.frame.ip(),
 383                         symbol.name.as_ref().map(|b| backtrace::SymbolName::new(b)),
 384                         symbol.filename.as_ref().map(|b| match b {
 385                             BytesOrWide::Bytes(w) => BytesOrWideString::Bytes(w),
 386                             BytesOrWide::Wide(w) => BytesOrWideString::Wide(w),
 387                         }),
 388                         symbol.lineno,
 389                     )?;
 390                 }
 391             }
 392         }
 393         f.finish()?;
 394         Ok(())
 395     }
 396 }
 397
 398 impl Capture {
 399     fn resolve(&mut self) {
 400         // If we're already resolved, nothing to do!
 401         if self.resolved {
 402             return;
 403         }
 404         self.resolved = true;
 405
 406         // Use the global backtrace lock to synchronize this as it's a
 407         // requirement of the `backtrace` crate, and then actually resolve
 408         // everything.
 409         let _lock = lock();
 410         for frame in self.frames.iter_mut() {
 411             let symbols = &mut frame.symbols;
 412             let frame = match &frame.frame {
 413                 RawFrame::Actual(frame) => frame,
 414                 #[cfg(test)]
 415                 RawFrame::Fake => unimplemented!(),
 416             };
 417             unsafe {
 418                 backtrace::resolve_frame_unsynchronized(frame, |symbol| {
 419                     symbols.push(BacktraceSymbol {
 420                         name: symbol.name().map(|m| m.as_bytes().to_vec()),
 421                         filename: symbol.filename_raw().map(|b| match b {
 422                             BytesOrWideString::Bytes(b) => BytesOrWide::Bytes(b.to_owned()),
 423                             BytesOrWideString::Wide(b) => BytesOrWide::Wide(b.to_owned()),
 424                         }),
 425                         lineno: symbol.lineno(),
 426                     });
 427                 });
 428             }
 429         }
 430     }
 431 }
 432
 433 impl RawFrame {
 434     fn ip(&self) -> *mut c_void {
 435         match self {
 436             RawFrame::Actual(frame) => frame.ip(),
 437             #[cfg(test)]
 438             RawFrame::Fake => 1 as *mut c_void,
 439         }
 440     }
 441 }
 442
 443 #[test]
 444 fn test_debug() {
 445     let backtrace = Backtrace {
 446         inner: Inner::Captured(Mutex::new(Capture {
 447             actual_start: 1,
 448             resolved: true,
 449             frames: vec![
 450                 BacktraceFrame {
 451                     frame: RawFrame::Fake,
 452                     symbols: vec![BacktraceSymbol {
 453                         name: Some(b"std::backtrace::Backtrace::create".to_vec()),
 454                         filename: Some(BytesOrWide::Bytes(b"rust/backtrace.rs".to_vec())),
 455                         lineno: Some(100),
 456                     }],
 457                 },
 458                 BacktraceFrame {
 459                     frame: RawFrame::Fake,
 460                     symbols: vec![BacktraceSymbol {
 461                         name: Some(b"__rust_maybe_catch_panic".to_vec()),
 462                         filename: None,
 463                         lineno: None,
 464                     }],
 465                 },
 466                 BacktraceFrame {
 467                     frame: RawFrame::Fake,
 468                     symbols: vec![
 469                         BacktraceSymbol {
 470                             name: Some(b"std::rt::lang_start_internal".to_vec()),
 471                             filename: Some(BytesOrWide::Bytes(b"rust/rt.rs".to_vec())),
 472                             lineno: Some(300),
 473                         },
 474                         BacktraceSymbol {
 475                             name: Some(b"std::rt::lang_start".to_vec()),
 476                             filename: Some(BytesOrWide::Bytes(b"rust/rt.rs".to_vec())),
 477                             lineno: Some(400),
 478                         },
 479                     ],
 480                 },
 481             ],
 482         })),
 483     };
 484
 485     #[rustfmt::skip]
 486     let expected = "Backtrace [\
 487     \n    { fn: \"__rust_maybe_catch_panic\" },\
 488     \n    { fn: \"std::rt::lang_start_internal\", file: \"rust/rt.rs\", line: 300 },\
 489     \n    { fn: \"std::rt::lang_start\", file: \"rust/rt.rs\", line: 400 },\
 490     \n]";
 491
 492     assert_eq!(format!("{:#?}", backtrace), expected);
 493 }