]> git.lizzy.rs Git - rust.git/blob - src/libstd/backtrace.rs
Get vaguely working with a test for checking output
[rust.git] / src / libstd / 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::fmt;
96 use crate::sync::atomic::{AtomicUsize, Ordering::SeqCst};
97 use crate::sync::Mutex;
98 use crate::sys_common::backtrace::{lock, output_filename};
99 use crate::vec::Vec;
100 use backtrace::BytesOrWideString;
101 use backtrace_rs as backtrace;
102
103 /// A captured OS thread stack backtrace.
104 ///
105 /// This type represents a stack backtrace for an OS thread captured at a
106 /// previous point in time. In some instances the `Backtrace` type may
107 /// internally be empty due to configuration. For more information see
108 /// `Backtrace::capture`.
109 #[derive(Debug)]
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 #[derive(Debug)]
131 enum Inner {
132     Unsupported,
133     Disabled,
134     Captured(Mutex<Capture>),
135 }
136
137 #[derive(Debug)]
138 struct Capture {
139     actual_start: usize,
140     resolved: bool,
141     frames: Vec<BacktraceFrame>,
142 }
143
144 fn _assert_send_sync() {
145     fn _assert<T: Send + Sync>() {}
146     _assert::<Backtrace>();
147 }
148
149 #[derive(Debug)]
150 struct BacktraceFrame {
151     frame: backtrace::Frame,
152     symbols: Vec<BacktraceSymbol>,
153 }
154
155 struct BacktraceSymbol {
156     name: Option<Vec<u8>>,
157     filename: Option<BytesOrWide>,
158     lineno: Option<u32>,
159 }
160
161 enum BytesOrWide {
162     Bytes(Vec<u8>),
163     Wide(Vec<u16>),
164 }
165
166 impl fmt::Debug for BacktraceSymbol {
167     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
168         fmt.debug_struct("BacktraceSymbol")
169             .field("name", &self.name.as_ref().map(|b| backtrace::SymbolName::new(b)))
170             .field("filename", &self.filename)
171             .field("lineno", &self.lineno)
172             .finish()
173     }
174 }
175
176 impl fmt::Debug for BytesOrWide {
177     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
178         output_filename(
179             fmt,
180             match self {
181                 BytesOrWide::Bytes(w) => BytesOrWideString::Bytes(w),
182                 BytesOrWide::Wide(w) => BytesOrWideString::Wide(w),
183             },
184             backtrace::PrintFmt::Full,
185             crate::env::current_dir().as_ref().ok(),
186         )
187     }
188 }
189
190 impl Backtrace {
191     /// Returns whether backtrace captures are enabled through environment
192     /// variables.
193     fn enabled() -> bool {
194         // Cache the result of reading the environment variables to make
195         // backtrace captures speedy, because otherwise reading environment
196         // variables every time can be somewhat slow.
197         static ENABLED: AtomicUsize = AtomicUsize::new(0);
198         match ENABLED.load(SeqCst) {
199             0 => {}
200             1 => return false,
201             _ => return true,
202         }
203         let enabled = match env::var("RUST_LIB_BACKTRACE") {
204             Ok(s) => s != "0",
205             Err(_) => match env::var("RUST_BACKTRACE") {
206                 Ok(s) => s != "0",
207                 Err(_) => false,
208             },
209         };
210         ENABLED.store(enabled as usize + 1, SeqCst);
211         return enabled;
212     }
213
214     /// Capture a stack backtrace of the current thread.
215     ///
216     /// This function will capture a stack backtrace of the current OS thread of
217     /// execution, returning a `Backtrace` type which can be later used to print
218     /// the entire stack trace or render it to a string.
219     ///
220     /// This function will be a noop if the `RUST_BACKTRACE` or
221     /// `RUST_LIB_BACKTRACE` backtrace variables are both not set. If either
222     /// environment variable is set and enabled then this function will actually
223     /// capture a backtrace. Capturing a backtrace can be both memory intensive
224     /// and slow, so these environment variables allow liberally using
225     /// `Backtrace::capture` and only incurring a slowdown when the environment
226     /// variables are set.
227     ///
228     /// To forcibly capture a backtrace regardless of environment variables, use
229     /// the `Backtrace::force_capture` function.
230     #[inline(never)] // want to make sure there's a frame here to remove
231     pub fn capture() -> Backtrace {
232         if !Backtrace::enabled() {
233             return Backtrace { inner: Inner::Disabled };
234         }
235         Backtrace::create(Backtrace::capture as usize)
236     }
237
238     /// Forcibly captures a full backtrace, regardless of environment variable
239     /// configuration.
240     ///
241     /// This function behaves the same as `capture` except that it ignores the
242     /// values of the `RUST_BACKTRACE` and `RUST_LIB_BACKTRACE` environment
243     /// variables, always capturing a backtrace.
244     ///
245     /// Note that capturing a backtrace can be an expensive operation on some
246     /// platforms, so this should be used with caution in performance-sensitive
247     /// parts of code.
248     #[inline(never)] // want to make sure there's a frame here to remove
249     pub fn force_capture() -> Backtrace {
250         Backtrace::create(Backtrace::force_capture as usize)
251     }
252
253     // Capture a backtrace which start just before the function addressed by
254     // `ip`
255     fn create(ip: usize) -> Backtrace {
256         let _lock = lock();
257         let mut frames = Vec::new();
258         let mut actual_start = None;
259         unsafe {
260             backtrace::trace_unsynchronized(|frame| {
261                 frames.push(BacktraceFrame { frame: frame.clone(), symbols: Vec::new() });
262                 if frame.symbol_address() as usize == ip && actual_start.is_none() {
263                     actual_start = Some(frames.len());
264                 }
265                 true
266             });
267         }
268
269         // If no frames came out assume that this is an unsupported platform
270         // since `backtrace` doesn't provide a way of learning this right now,
271         // and this should be a good enough approximation.
272         let inner = if frames.len() == 0 {
273             Inner::Unsupported
274         } else {
275             Inner::Captured(Mutex::new(Capture {
276                 actual_start: actual_start.unwrap_or(0),
277                 frames,
278                 resolved: false,
279             }))
280         };
281
282         Backtrace { inner }
283     }
284
285     /// Returns the status of this backtrace, indicating whether this backtrace
286     /// request was unsupported, disabled, or a stack trace was actually
287     /// captured.
288     pub fn status(&self) -> BacktraceStatus {
289         match self.inner {
290             Inner::Unsupported => BacktraceStatus::Unsupported,
291             Inner::Disabled => BacktraceStatus::Disabled,
292             Inner::Captured(_) => BacktraceStatus::Captured,
293         }
294     }
295 }
296
297 impl fmt::Display for Backtrace {
298     fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result {
299         let mut capture = match &self.inner {
300             Inner::Unsupported => return fmt.write_str("unsupported backtrace"),
301             Inner::Disabled => return fmt.write_str("disabled backtrace"),
302             Inner::Captured(c) => c.lock().unwrap(),
303         };
304         capture.resolve();
305
306         let full = fmt.alternate();
307         let (frames, style) = if full {
308             (&capture.frames[..], backtrace::PrintFmt::Full)
309         } else {
310             (&capture.frames[capture.actual_start..], backtrace::PrintFmt::Short)
311         };
312
313         // When printing paths we try to strip the cwd if it exists, otherwise
314         // we just print the path as-is. Note that we also only do this for the
315         // short format, because if it's full we presumably want to print
316         // everything.
317         let cwd = crate::env::current_dir();
318         let mut print_path = move |fmt: &mut fmt::Formatter<'_>, path: BytesOrWideString<'_>| {
319             output_filename(fmt, path, style, cwd.as_ref().ok())
320         };
321
322         let mut f = backtrace::BacktraceFmt::new(fmt, style, &mut print_path);
323         f.add_context()?;
324         for frame in frames {
325             let mut f = f.frame();
326             if frame.symbols.is_empty() {
327                 f.print_raw(frame.frame.ip(), None, None, None)?;
328             } else {
329                 for symbol in frame.symbols.iter() {
330                     f.print_raw(
331                         frame.frame.ip(),
332                         symbol.name.as_ref().map(|b| backtrace::SymbolName::new(b)),
333                         symbol.filename.as_ref().map(|b| match b {
334                             BytesOrWide::Bytes(w) => BytesOrWideString::Bytes(w),
335                             BytesOrWide::Wide(w) => BytesOrWideString::Wide(w),
336                         }),
337                         symbol.lineno,
338                     )?;
339                 }
340             }
341         }
342         f.finish()?;
343         Ok(())
344     }
345 }
346
347 impl Capture {
348     fn resolve(&mut self) {
349         // If we're already resolved, nothing to do!
350         if self.resolved {
351             return;
352         }
353         self.resolved = true;
354
355         // Use the global backtrace lock to synchronize this as it's a
356         // requirement of the `backtrace` crate, and then actually resolve
357         // everything.
358         let _lock = lock();
359         for frame in self.frames.iter_mut() {
360             let symbols = &mut frame.symbols;
361             unsafe {
362                 backtrace::resolve_frame_unsynchronized(&frame.frame, |symbol| {
363                     symbols.push(BacktraceSymbol {
364                         name: symbol.name().map(|m| m.as_bytes().to_vec()),
365                         filename: symbol.filename_raw().map(|b| match b {
366                             BytesOrWideString::Bytes(b) => BytesOrWide::Bytes(b.to_owned()),
367                             BytesOrWideString::Wide(b) => BytesOrWide::Wide(b.to_owned()),
368                         }),
369                         lineno: symbol.lineno(),
370                     });
371                 });
372             }
373         }
374     }
375 }
376
377 #[cfg(test)]
378 mod tests {
379     use super::*;
380
381     #[test]
382     fn debug_backtrace_fmt() {
383         let bt = Backtrace::capture();
384         eprintln!("uncaptured: {:?}", bt);
385         let bt = Backtrace::force_capture();
386         eprintln!("captured: {:?}", bt);
387         eprintln!("display print: {}", bt);
388         eprintln!("resolved: {:?}", bt);
389         unimplemented!();
390     }
391 }