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")]
69 // NB: A note on resolution of a backtrace:
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`).
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
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.
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.
95 use crate::ffi::c_void;
97 use crate::sync::atomic::{AtomicUsize, Ordering::SeqCst};
98 use crate::sync::Mutex;
99 use crate::sys_common::backtrace::{lock, output_filename};
101 use backtrace::BytesOrWideString;
102 use backtrace_rs as backtrace;
104 /// A captured OS thread stack backtrace.
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 {
114 /// The current status of a backtrace, indicating whether it was captured or
115 /// whether it is empty for some other reason.
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(Mutex<Capture>),
139 frames: Vec<BacktraceFrame>,
142 fn _assert_send_sync() {
143 fn _assert<T: Send + Sync>() {}
144 _assert::<Backtrace>();
147 struct BacktraceFrame {
149 symbols: Vec<BacktraceSymbol>,
153 Actual(backtrace::Frame),
158 struct BacktraceSymbol {
159 name: Option<Vec<u8>>,
160 filename: Option<BytesOrWide>,
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(),
178 let frames = &capture.frames[capture.actual_start..];
180 write!(fmt, "Backtrace ")?;
182 let mut dbg = fmt.debug_list();
184 for frame in frames {
185 if frame.frame.ip().is_null() {
189 dbg.entries(&frame.symbols);
196 impl fmt::Debug for BacktraceSymbol {
197 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
200 if let Some(fn_name) = self.name.as_ref().map(|b| backtrace::SymbolName::new(b)) {
201 write!(fmt, "fn: \"{:#}\"", fn_name)?;
203 write!(fmt, "fn: <unknown>")?;
206 if let Some(fname) = self.filename.as_ref() {
207 write!(fmt, ", file: \"{:?}\"", fname)?;
210 if let Some(line) = self.lineno.as_ref() {
211 write!(fmt, ", line: {:?}", line)?;
218 impl fmt::Debug for BytesOrWide {
219 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
223 BytesOrWide::Bytes(w) => BytesOrWideString::Bytes(w),
224 BytesOrWide::Wide(w) => BytesOrWideString::Wide(w),
226 backtrace::PrintFmt::Short,
227 crate::env::current_dir().as_ref().ok(),
233 /// Returns whether backtrace captures are enabled through environment
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) {
245 let enabled = match env::var("RUST_LIB_BACKTRACE") {
247 Err(_) => match env::var("RUST_BACKTRACE") {
252 ENABLED.store(enabled as usize + 1, SeqCst);
256 /// Capture a stack backtrace of the current thread.
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.
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.
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 };
277 Backtrace::create(Backtrace::capture as usize)
280 /// Forcibly captures a full backtrace, regardless of environment variable
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.
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
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)
295 // Capture a backtrace which start just before the function addressed by
297 fn create(ip: usize) -> Backtrace {
299 let mut frames = Vec::new();
300 let mut actual_start = None;
302 backtrace::trace_unsynchronized(|frame| {
303 frames.push(BacktraceFrame {
304 frame: RawFrame::Actual(frame.clone()),
307 if frame.symbol_address() as usize == ip && actual_start.is_none() {
308 actual_start = Some(frames.len());
314 // If no frames came out assume that this is an unsupported platform
315 // since `backtrace` doesn't provide a way of learning this right now,
316 // and this should be a good enough approximation.
317 let inner = if frames.is_empty() {
320 Inner::Captured(Mutex::new(Capture {
321 actual_start: actual_start.unwrap_or(0),
330 /// Returns the status of this backtrace, indicating whether this backtrace
331 /// request was unsupported, disabled, or a stack trace was actually
333 pub fn status(&self) -> BacktraceStatus {
335 Inner::Unsupported => BacktraceStatus::Unsupported,
336 Inner::Disabled => BacktraceStatus::Disabled,
337 Inner::Captured(_) => BacktraceStatus::Captured,
342 impl fmt::Display for Backtrace {
343 fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
344 let mut capture = match &self.inner {
345 Inner::Unsupported => return fmt.write_str("unsupported backtrace"),
346 Inner::Disabled => return fmt.write_str("disabled backtrace"),
347 Inner::Captured(c) => c.lock().unwrap(),
351 let full = fmt.alternate();
352 let (frames, style) = if full {
353 (&capture.frames[..], backtrace::PrintFmt::Full)
355 (&capture.frames[capture.actual_start..], backtrace::PrintFmt::Short)
358 // When printing paths we try to strip the cwd if it exists, otherwise
359 // we just print the path as-is. Note that we also only do this for the
360 // short format, because if it's full we presumably want to print
362 let cwd = crate::env::current_dir();
363 let mut print_path = move |fmt: &mut fmt::Formatter<'_>, path: BytesOrWideString<'_>| {
364 output_filename(fmt, path, style, cwd.as_ref().ok())
367 let mut f = backtrace::BacktraceFmt::new(fmt, style, &mut print_path);
369 for frame in frames {
370 let mut f = f.frame();
371 if frame.symbols.is_empty() {
372 f.print_raw(frame.frame.ip(), None, None, None)?;
374 for symbol in frame.symbols.iter() {
377 symbol.name.as_ref().map(|b| backtrace::SymbolName::new(b)),
378 symbol.filename.as_ref().map(|b| match b {
379 BytesOrWide::Bytes(w) => BytesOrWideString::Bytes(w),
380 BytesOrWide::Wide(w) => BytesOrWideString::Wide(w),
393 fn resolve(&mut self) {
394 // If we're already resolved, nothing to do!
398 self.resolved = true;
400 // Use the global backtrace lock to synchronize this as it's a
401 // requirement of the `backtrace` crate, and then actually resolve
404 for frame in self.frames.iter_mut() {
405 let symbols = &mut frame.symbols;
406 let frame = match &frame.frame {
407 RawFrame::Actual(frame) => frame,
409 RawFrame::Fake => unimplemented!(),
412 backtrace::resolve_frame_unsynchronized(frame, |symbol| {
413 symbols.push(BacktraceSymbol {
414 name: symbol.name().map(|m| m.as_bytes().to_vec()),
415 filename: symbol.filename_raw().map(|b| match b {
416 BytesOrWideString::Bytes(b) => BytesOrWide::Bytes(b.to_owned()),
417 BytesOrWideString::Wide(b) => BytesOrWide::Wide(b.to_owned()),
419 lineno: symbol.lineno(),
428 fn ip(&self) -> *mut c_void {
430 RawFrame::Actual(frame) => frame.ip(),
432 RawFrame::Fake => 1 as *mut c_void,
439 let backtrace = Backtrace {
440 inner: Inner::Captured(Mutex::new(Capture {
445 frame: RawFrame::Fake,
446 symbols: vec![BacktraceSymbol {
447 name: Some(b"std::backtrace::Backtrace::create".to_vec()),
448 filename: Some(BytesOrWide::Bytes(b"rust/backtrace.rs".to_vec())),
453 frame: RawFrame::Fake,
454 symbols: vec![BacktraceSymbol {
455 name: Some(b"__rust_maybe_catch_panic".to_vec()),
461 frame: RawFrame::Fake,
464 name: Some(b"std::rt::lang_start_internal".to_vec()),
465 filename: Some(BytesOrWide::Bytes(b"rust/rt.rs".to_vec())),
469 name: Some(b"std::rt::lang_start".to_vec()),
470 filename: Some(BytesOrWide::Bytes(b"rust/rt.rs".to_vec())),
480 let expected = "Backtrace [\
481 \n { fn: \"__rust_maybe_catch_panic\" },\
482 \n { fn: \"std::rt::lang_start_internal\", file: \"rust/rt.rs\", line: 300 },\
483 \n { fn: \"std::rt::lang_start\", file: \"rust/rt.rs\", line: 400 },\
486 assert_eq!(format!("{:#?}", backtrace), expected);