1 //! A library for acquiring a backtrace at runtime
2 //!
3 //! This library is meant to supplement the `RUST_BACKTRACE=1` support of the
4 //! standard library by allowing an acquisition of a backtrace at runtime
5 //! programmatically. The backtraces generated by this library do not need to be
6 //! parsed, for example, and expose the functionality of multiple backend
7 //! implementations.
8 //!
9 //! # Implementation
10 //!
11 //! This library makes use of a number of strategies for actually acquiring a
12 //! backtrace. For example unix uses libgcc's libunwind bindings by default to
13 //! acquire a backtrace, but coresymbolication or dladdr is used on OSX to
14 //! acquire symbol names while linux uses gcc's libbacktrace.
15 //!
16 //! When using the default feature set of this library the "most reasonable" set
17 //! of defaults is chosen for the current platform, but the features activated
18 //! can also be controlled at a finer granularity.
19 //!
20 //! # Platform Support
21 //!
22 //! Currently this library is verified to work on Linux, OSX, and Windows, but
23 //! it may work on other platforms as well. Note that the quality of the
24 //! backtrace may vary across platforms.
25 //!
26 //! # API Principles
27 //!
28 //! This library attempts to be as flexible as possible to accommodate different
29 //! backend implementations of acquiring a backtrace. Consequently the currently
30 //! exported functions are closure-based as opposed to the likely expected
31 //! iterator-based versions. This is done due to limitations of the underlying
32 //! APIs used from the system.
33 //!
34 //! # Usage
35 //!
36 //! First, add this to your Cargo.toml
37 //!
38 //! ```toml
39 //! [dependencies]
40 //! backtrace = "0.2"
41 //! ```
42 //!
43 //! Next:
44 //!
45 //! ```
46 //! extern crate backtrace;
47 //!
48 //! fn main() {
49 //! backtrace::trace(|frame| {
50 //! let ip = frame.ip();
51 //! let symbol_address = frame.symbol_address();
52 //!
53 //! // Resolve this instruction pointer to a symbol name
54 //! backtrace::resolve(ip, |symbol| {
55 //! if let Some(name) = symbol.name() {
56 //! // ...
57 //! }
58 //! if let Some(filename) = symbol.filename() {
59 //! // ...
60 //! }
61 //! });
62 //!
63 //! true // keep going to the next frame
64 //! });
65 //! }
66 //! ```
67
68 #![doc(html_root_url = "https://docs.rs/backtrace")]
69 #![deny(missing_docs)]
70 #![deny(warnings)]
71
72 #[cfg(unix)]
73 extern crate libc;
74 #[cfg(all(windows, feature = "winapi"))] extern crate winapi;
75
76 #[cfg(feature = "serde_derive")]
77 #[cfg_attr(feature = "serde_derive", macro_use)]
78 extern crate serde_derive;
79
80 #[cfg(feature = "rustc-serialize")]
81 extern crate rustc_serialize;
82
83 #[macro_use]
84 extern crate cfg_if;
85
86 extern crate rustc_demangle;
87
88 #[cfg(feature = "cpp_demangle")]
89 extern crate cpp_demangle;
90
91 cfg_if! {
92 if #[cfg(all(feature = "gimli-symbolize", unix, target_os = "linux"))] {
93 extern crate addr2line;
94 extern crate findshlibs;
95 extern crate gimli;
96 extern crate memmap;
97 extern crate object;
98 }
99 }
100
101 #[allow(dead_code)] // not used everywhere
102 #[cfg(unix)]
103 #[macro_use]
104 mod dylib;
105
106 pub use backtrace::{trace, Frame};
107 mod backtrace;
108
109 pub use symbolize::{resolve, Symbol, SymbolName};
110 mod symbolize;
111
112 pub use capture::{Backtrace, BacktraceFrame, BacktraceSymbol};
113 mod capture;
114
115 #[allow(dead_code)]
116 struct Bomb {
117 enabled: bool,
118 }
119
120 #[allow(dead_code)]
121 impl Drop for Bomb {
drop(&mut self)122 fn drop(&mut self) {
123 if self.enabled {
124 panic!("cannot panic during the backtrace function");
125 }
126 }
127 }
128
129 #[allow(dead_code)]
130 mod lock {
131 use std::cell::Cell;
132 use std::mem;
133 use std::sync::{Once, Mutex, MutexGuard, ONCE_INIT};
134
135 pub struct LockGuard(MutexGuard<'static, ()>);
136
137 static mut LOCK: *mut Mutex<()> = 0 as *mut _;
138 static INIT: Once = ONCE_INIT;
139 thread_local!(static LOCK_HELD: Cell<bool> = Cell::new(false));
140
141 impl Drop for LockGuard {
drop(&mut self)142 fn drop(&mut self) {
143 LOCK_HELD.with(|slot| {
144 assert!(slot.get());
145 slot.set(false);
146 });
147 }
148 }
149
lock() -> Option<LockGuard>150 pub fn lock() -> Option<LockGuard> {
151 if LOCK_HELD.with(|l| l.get()) {
152 return None
153 }
154 LOCK_HELD.with(|s| s.set(true));
155 unsafe {
156 INIT.call_once(|| {
157 LOCK = mem::transmute(Box::new(Mutex::new(())));
158 });
159 Some(LockGuard((*LOCK).lock().unwrap()))
160 }
161 }
162 }
163
164 // requires external synchronization
165 #[cfg(all(windows, feature = "dbghelp"))]
dbghelp_init()166 unsafe fn dbghelp_init() {
167 use winapi::shared::minwindef;
168 use winapi::um::{dbghelp, processthreadsapi};
169
170 static mut INITIALIZED: bool = false;
171
172 if !INITIALIZED {
173 dbghelp::SymInitializeW(processthreadsapi::GetCurrentProcess(),
174 0 as *mut _,
175 minwindef::TRUE);
176 INITIALIZED = true;
177 }
178 }
179