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

use std::fmt;
use std::os::raw::c_void;

use debug_builders::DebugStruct;

/// 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 funciton, 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 trait Symbol {
    /// Returns the name of this function as a byte array (may not always be
    /// valid UTF-8).
    fn name(&self) -> Option<&[u8]> { None }

    /// Returns the starting address of this function.
    fn addr(&self) -> Option<*mut c_void> { None }

    /// 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`.
    fn filename(&self) -> Option<&[u8]> { None }

    /// 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.
    fn lineno(&self) -> Option<u32> { None }
}

/// 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 addres (if available).
///
/// # Example
///
/// ```
/// extern crate backtrace;
///
/// fn main() {
///     backtrace::trace(&mut |frame| {
///         let ip = frame.ip();
///
///         backtrace::resolve(ip, &mut |symbol| {
///             // ...
///         });
///
///         false // only look at the top frame
///     });
/// }
/// ```
pub fn resolve(addr: *mut c_void, cb: &mut FnMut(&Symbol)) {
    resolve_imp(addr, cb)
}

impl fmt::Debug for Symbol {
    fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
        let mut d = DebugStruct::new(f, "Symbol");
        if let Some(name) = self.name() {
            d = d.field("name", &String::from_utf8_lossy(name));
        }
        if let Some(addr) = self.addr() {
            d = d.field("addr", &addr);
        }
        if let Some(filename) = self.filename() {
            d = d.field("filename", &String::from_utf8_lossy(filename));
        }
        if let Some(lineno) = self.lineno() {
            d = d.field("lineno", &lineno);
        }
        d.finish()
    }
}

cfg_if! {
    if #[cfg(all(windows, feature = "dbghelp"))] {
        mod dbghelp;
        use self::dbghelp::resolve as resolve_imp;
    } else if #[cfg(all(feature = "libbacktrace", unix,
                        not(target_os = "macos")))] {
        mod libbacktrace;
        use self::libbacktrace::resolve as resolve_imp;
    } else if #[cfg(all(unix, feature = "dladdr"))] {
        mod dladdr;
        use self::dladdr::resolve as resolve_imp;
    } else {
        mod noop;
        use self::noop::resolve as resolve_imp;
    }
}