README.md
1# backtrace-rs
2
3[](https://travis-ci.org/alexcrichton/backtrace-rs)
4[](https://ci.appveyor.com/project/alexcrichton/backtrace-rs)
5
6[Documentation](http://alexcrichton.com/backtrace-rs)
7
8A library for acquiring backtraces at runtime for Rust. This library aims to
9enhance the support given by the standard library at `std::rt` by providing a
10more stable and programmatic interface.
11
12## Install
13
14```toml
15[dependencies]
16backtrace = "0.2"
17```
18
19```rust
20extern crate backtrace;
21```
22
23## Usage
24
25To simply capture a backtrace and defer dealing with it until a later time,
26you can use the top-level `Backtrace` type.
27
28```rust
29extern crate backtrace;
30
31use backtrace::Backtrace;
32
33fn main() {
34 let bt = Backtrace::new();
35
36 // do_some_work();
37
38 println!("{:?}", bt);
39}
40```
41
42If, however, you'd like more raw access to the actual tracing functionality, you
43can use the `trace` and `resolve` functions directly.
44
45```rust
46extern crate backtrace;
47
48fn 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## Platform Support
69
70This library currently supports OSX, Linux, and Windows. Support for other
71platforms is always welcome!
72
73## License
74
75`backtrace-rs` is primarily distributed under the terms of both the MIT license
76and the Apache License (Version 2.0), with portions covered by various BSD-like
77licenses.
78
79See LICENSE-APACHE, and LICENSE-MIT for details.
80
){kind=link}