backtrace 0.1.5

A library to acquire a stack trace (backtrace) at runtime in a Rust program. 
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;
    }
}