]>
Commit | Line | Data |
---|---|---|
e1599b0c XL |
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; | |
ba9703b0 | 95 | use crate::ffi::c_void; |
e1599b0c XL |
96 | use crate::fmt; |
97 | use crate::sync::atomic::{AtomicUsize, Ordering::SeqCst}; | |
98 | use crate::sync::Mutex; | |
60c5eb7d | 99 | use crate::sys_common::backtrace::{lock, output_filename}; |
e1599b0c | 100 | use crate::vec::Vec; |
e1599b0c | 101 | use backtrace::BytesOrWideString; |
60c5eb7d | 102 | use backtrace_rs as backtrace; |
e1599b0c XL |
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] | |
e74abb32 | 117 | #[derive(Debug, PartialEq, Eq)] |
e1599b0c XL |
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 { | |
ba9703b0 | 148 | frame: RawFrame, |
e1599b0c XL |
149 | symbols: Vec<BacktraceSymbol>, |
150 | } | |
151 | ||
ba9703b0 XL |
152 | enum RawFrame { |
153 | Actual(backtrace::Frame), | |
154 | #[cfg(test)] | |
155 | Fake, | |
156 | } | |
157 | ||
e1599b0c XL |
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 | ||
74b04a01 XL |
169 | impl fmt::Debug for Backtrace { |
170 | fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { | |
171 | let mut capture = match &self.inner { | |
ba9703b0 XL |
172 | Inner::Unsupported => return fmt.write_str("<unsupported>"), |
173 | Inner::Disabled => return fmt.write_str("<disabled>"), | |
74b04a01 XL |
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 { | |
ba9703b0 | 203 | write!(fmt, "fn: <unknown>")?; |
74b04a01 XL |
204 | } |
205 | ||
206 | if let Some(fname) = self.filename.as_ref() { | |
ba9703b0 | 207 | write!(fmt, ", file: \"{:?}\"", fname)?; |
74b04a01 XL |
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 | ||
e1599b0c XL |
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); | |
ba9703b0 | 253 | enabled |
e1599b0c XL |
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 | // Capture a backtrace which start just before the function addressed by | |
296 | // `ip` | |
297 | fn create(ip: usize) -> Backtrace { | |
298 | let _lock = lock(); | |
299 | let mut frames = Vec::new(); | |
300 | let mut actual_start = None; | |
301 | unsafe { | |
302 | backtrace::trace_unsynchronized(|frame| { | |
ba9703b0 XL |
303 | frames.push(BacktraceFrame { |
304 | frame: RawFrame::Actual(frame.clone()), | |
305 | symbols: Vec::new(), | |
306 | }); | |
e1599b0c XL |
307 | if frame.symbol_address() as usize == ip && actual_start.is_none() { |
308 | actual_start = Some(frames.len()); | |
309 | } | |
310 | true | |
311 | }); | |
312 | } | |
313 | ||
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. | |
74b04a01 | 317 | let inner = if frames.is_empty() { |
e1599b0c XL |
318 | Inner::Unsupported |
319 | } else { | |
320 | Inner::Captured(Mutex::new(Capture { | |
321 | actual_start: actual_start.unwrap_or(0), | |
322 | frames, | |
323 | resolved: false, | |
324 | })) | |
325 | }; | |
326 | ||
327 | Backtrace { inner } | |
328 | } | |
329 | ||
330 | /// Returns the status of this backtrace, indicating whether this backtrace | |
331 | /// request was unsupported, disabled, or a stack trace was actually | |
332 | /// captured. | |
333 | pub fn status(&self) -> BacktraceStatus { | |
334 | match self.inner { | |
335 | Inner::Unsupported => BacktraceStatus::Unsupported, | |
336 | Inner::Disabled => BacktraceStatus::Disabled, | |
337 | Inner::Captured(_) => BacktraceStatus::Captured, | |
338 | } | |
339 | } | |
340 | } | |
341 | ||
342 | impl fmt::Display for Backtrace { | |
343 | fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { | |
e1599b0c XL |
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(), | |
348 | }; | |
349 | capture.resolve(); | |
350 | ||
351 | let full = fmt.alternate(); | |
352 | let (frames, style) = if full { | |
353 | (&capture.frames[..], backtrace::PrintFmt::Full) | |
354 | } else { | |
355 | (&capture.frames[capture.actual_start..], backtrace::PrintFmt::Short) | |
356 | }; | |
357 | ||
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 | |
361 | // everything. | |
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()) | |
365 | }; | |
366 | ||
367 | let mut f = backtrace::BacktraceFmt::new(fmt, style, &mut print_path); | |
368 | f.add_context()?; | |
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)?; | |
373 | } else { | |
374 | for symbol in frame.symbols.iter() { | |
375 | f.print_raw( | |
376 | frame.frame.ip(), | |
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), | |
381 | }), | |
382 | symbol.lineno, | |
383 | )?; | |
384 | } | |
385 | } | |
386 | } | |
387 | f.finish()?; | |
388 | Ok(()) | |
389 | } | |
390 | } | |
391 | ||
392 | impl Capture { | |
393 | fn resolve(&mut self) { | |
394 | // If we're already resolved, nothing to do! | |
395 | if self.resolved { | |
396 | return; | |
397 | } | |
398 | self.resolved = true; | |
399 | ||
400 | // Use the global backtrace lock to synchronize this as it's a | |
401 | // requirement of the `backtrace` crate, and then actually resolve | |
402 | // everything. | |
403 | let _lock = lock(); | |
404 | for frame in self.frames.iter_mut() { | |
405 | let symbols = &mut frame.symbols; | |
ba9703b0 XL |
406 | let frame = match &frame.frame { |
407 | RawFrame::Actual(frame) => frame, | |
408 | #[cfg(test)] | |
409 | RawFrame::Fake => unimplemented!(), | |
410 | }; | |
e1599b0c | 411 | unsafe { |
ba9703b0 | 412 | backtrace::resolve_frame_unsynchronized(frame, |symbol| { |
e1599b0c XL |
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()), | |
418 | }), | |
419 | lineno: symbol.lineno(), | |
420 | }); | |
421 | }); | |
422 | } | |
423 | } | |
424 | } | |
425 | } | |
ba9703b0 XL |
426 | |
427 | impl RawFrame { | |
428 | fn ip(&self) -> *mut c_void { | |
429 | match self { | |
430 | RawFrame::Actual(frame) => frame.ip(), | |
431 | #[cfg(test)] | |
432 | RawFrame::Fake => 1 as *mut c_void, | |
433 | } | |
434 | } | |
435 | } | |
436 | ||
437 | #[test] | |
438 | fn test_debug() { | |
439 | let backtrace = Backtrace { | |
440 | inner: Inner::Captured(Mutex::new(Capture { | |
441 | actual_start: 1, | |
442 | resolved: true, | |
443 | frames: vec![ | |
444 | BacktraceFrame { | |
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())), | |
449 | lineno: Some(100), | |
450 | }], | |
451 | }, | |
452 | BacktraceFrame { | |
453 | frame: RawFrame::Fake, | |
454 | symbols: vec![BacktraceSymbol { | |
455 | name: Some(b"__rust_maybe_catch_panic".to_vec()), | |
456 | filename: None, | |
457 | lineno: None, | |
458 | }], | |
459 | }, | |
460 | BacktraceFrame { | |
461 | frame: RawFrame::Fake, | |
462 | symbols: vec![ | |
463 | BacktraceSymbol { | |
464 | name: Some(b"std::rt::lang_start_internal".to_vec()), | |
465 | filename: Some(BytesOrWide::Bytes(b"rust/rt.rs".to_vec())), | |
466 | lineno: Some(300), | |
467 | }, | |
468 | BacktraceSymbol { | |
469 | name: Some(b"std::rt::lang_start".to_vec()), | |
470 | filename: Some(BytesOrWide::Bytes(b"rust/rt.rs".to_vec())), | |
471 | lineno: Some(400), | |
472 | }, | |
473 | ], | |
474 | }, | |
475 | ], | |
476 | })), | |
477 | }; | |
478 | ||
479 | #[rustfmt::skip] | |
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 },\ | |
484 | \n]"; | |
485 | ||
486 | assert_eq!(format!("{:#?}", backtrace), expected); | |
487 | } |