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 //! # // Unsafe here so test passes on no_std.
50 //! # #[cfg(feature = "std")] {
51 //! backtrace::trace(|frame| {
52 //! let ip = frame.ip();
53 //! let symbol_address = frame.symbol_address();
54 //!
55 //! // Resolve this instruction pointer to a symbol name
56 //! backtrace::resolve(ip, |symbol| {
57 //! if let Some(name) = symbol.name() {
58 //! // ...
59 //! }
60 //! if let Some(filename) = symbol.filename() {
61 //! // ...
62 //! }
63 //! });
64 //!
65 //! true // keep going to the next frame
66 //! });
67 //! }
68 //! # }
69 //! ```
70
71 #![doc(html_root_url = "https://docs.rs/backtrace")]
72 #![deny(missing_docs)]
73 #![no_std]
74
75 #[cfg(feature = "std")]
76 #[macro_use] extern crate std;
77
78 #[cfg(unix)]
79 extern crate libc;
80 #[cfg(windows)]
81 extern crate winapi;
82
83 #[cfg(feature = "serde_derive")]
84 #[cfg_attr(feature = "serde_derive", macro_use)]
85 extern crate serde_derive;
86
87 #[cfg(feature = "rustc-serialize")]
88 extern crate rustc_serialize;
89
90 #[macro_use]
91 extern crate cfg_if;
92
93 extern crate rustc_demangle;
94
95 #[cfg(feature = "cpp_demangle")]
96 extern crate cpp_demangle;
97
98 cfg_if! {
99 if #[cfg(all(feature = "gimli-symbolize", unix, target_os = "linux"))] {
100 extern crate addr2line;
101 extern crate findshlibs;
102 extern crate gimli;
103 extern crate memmap;
104 extern crate object;
105 }
106 }
107
108 #[allow(dead_code)] // not used everywhere
109 #[cfg(unix)]
110 #[macro_use]
111 mod dylib;
112
113 pub use backtrace::{trace_unsynchronized, Frame};
114 mod backtrace;
115
116 pub use symbolize::{resolve_unsynchronized, Symbol, SymbolName};
117 mod symbolize;
118
119 pub use types::BytesOrWideString;
120 mod types;
121
122 cfg_if! {
123 if #[cfg(feature = "std")] {
124 pub use backtrace::trace;
125 pub use symbolize::resolve;
126 pub use capture::{Backtrace, BacktraceFrame, BacktraceSymbol};
127 mod capture;
128 }
129 }
130
131 #[allow(dead_code)]
132 struct Bomb {
133 enabled: bool,
134 }
135
136 #[allow(dead_code)]
137 impl Drop for Bomb {
drop(&mut self)138 fn drop(&mut self) {
139 if self.enabled {
140 panic!("cannot panic during the backtrace function");
141 }
142 }
143 }
144
145 #[allow(dead_code)]
146 #[cfg(feature = "std")]
147 mod lock {
148 use std::cell::Cell;
149 use std::boxed::Box;
150 use std::sync::{Once, Mutex, MutexGuard, ONCE_INIT};
151
152 pub struct LockGuard(MutexGuard<'static, ()>);
153
154 static mut LOCK: *mut Mutex<()> = 0 as *mut _;
155 static INIT: Once = ONCE_INIT;
156 thread_local!(static LOCK_HELD: Cell<bool> = Cell::new(false));
157
158 impl Drop for LockGuard {
drop(&mut self)159 fn drop(&mut self) {
160 LOCK_HELD.with(|slot| {
161 assert!(slot.get());
162 slot.set(false);
163 });
164 }
165 }
166
lock() -> Option<LockGuard>167 pub fn lock() -> Option<LockGuard> {
168 if LOCK_HELD.with(|l| l.get()) {
169 return None
170 }
171 LOCK_HELD.with(|s| s.set(true));
172 unsafe {
173 INIT.call_once(|| {
174 LOCK = Box::into_raw(Box::new(Mutex::new(())));
175 });
176 Some(LockGuard((*LOCK).lock().unwrap()))
177 }
178 }
179 }
180
181 // requires external synchronization
182 #[cfg(all(windows, feature = "dbghelp"))]
dbghelp_init()183 unsafe fn dbghelp_init() {
184 use winapi::shared::minwindef;
185 use winapi::um::{dbghelp, processthreadsapi};
186
187 static mut INITIALIZED: bool = false;
188
189 if !INITIALIZED {
190 dbghelp::SymInitializeW(processthreadsapi::GetCurrentProcess(),
191 0 as *mut _,
192 minwindef::TRUE);
193 INITIALIZED = true;
194 }
195 }
196