1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119
use alloc::borrow::Cow;
use alloc::str;
use core::fmt;
use addr2line::gimli;
use addr2line::Context;
mod freestanding;
use self::freestanding::resolve as resolve_imp;
use self::freestanding::Symbol as SymbolImp;
/// Resolve an address to a symbol, passing the symbol to the specified
/// closure.
///
/// This function will look up the given address in areas such as the local
/// symbol table, dynamic symbol table, or DWARF debug info (depending on the
/// activated implementation) to find symbols to yield.
///
/// The closure may not be called if resolution could not be performed, and it
/// also may be called more than once in the case of inlined functions.
///
/// Symbols yielded represent the execution at the specified `addr`, returning
/// file/line pairs for that address (if available).
///
/// # Example
///
/// ```
/// extern crate backtrace;
///
/// fn main() {
/// backtrace::trace(|frame| {
/// let ip = frame.ip();
///
/// backtrace::resolve(ip, |symbol| {
/// // ...
/// });
///
/// false // only look at the top frame
/// });
/// }
/// ```
pub fn resolve<F: FnMut(&Symbol)>(
ctxt: Option<&Context<gimli::EndianRcSlice<gimli::RunTimeEndian>>>,
offset: u64,
addr: *mut u8,
mut cb: F,
) -> Result<(), addr2line::gimli::Error> {
resolve_imp(ctxt, offset, addr, &mut cb)
}
/// A trait representing the resolution of a symbol in a file.
///
/// This trait is yielded as a trait object to the closure given to the
/// `backtrace::resolve` function, and it is virtually dispatched as it's
/// unknown which implementation is behind it.
///
/// A symbol can give contextual information about a function, for example the
/// name, filename, line number, precise address, etc. Not all information is
/// always available in a symbol, however, so all methods return an `Option`.
pub struct Symbol {
inner: SymbolImp,
}
impl Symbol {
/// Returns the name of this function.
///
/// The returned structure can be used to query various properties about the
/// symbol name:
///
/// * The `Display` implementation will print out the demangled symbol.
/// * The raw `str` value of the symbol can be accessed (if it's valid
/// utf-8).
/// * The raw bytes for the symbol name can be accessed.
pub fn name(&self) -> Option<Cow<str>> {
self.inner.name()
}
/// Returns the starting address of this function.
pub fn addr(&self) -> Option<*mut u8> {
self.inner.addr()
}
/// Returns the file name where this function was defined.
///
/// This is currently only available when libbacktrace is being used (e.g.
/// unix platforms other than OSX) and when a binary is compiled with
/// debuginfo. If neither of these conditions is met then this will likely
/// return `None`.
pub fn filename(&self) -> Option<&str> {
self.inner.filename()
}
/// Returns the line number for where this symbol is currently executing.
///
/// This return value is typically `Some` if `filename` returns `Some`, and
/// is consequently subject to similar caveats.
pub fn lineno(&self) -> Option<u32> {
self.inner.lineno()
}
}
impl fmt::Debug for Symbol {
fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
let mut d = f.debug_struct("Symbol");
if let Some(name) = self.name() {
d.field("name", &name);
}
if let Some(addr) = self.addr() {
d.field("addr", &addr);
}
if let Some(filename) = self.filename() {
d.field("filename", &filename);
}
if let Some(lineno) = self.lineno() {
d.field("lineno", &lineno);
}
d.finish()
}
}