README.md
1# addr2line
2
3[ ](https://crates.io/crates/addr2line)
4[](https://docs.rs/addr2line/)
5[](https://travis-ci.org/gimli-rs/addr2line)
6[](https://coveralls.io/github/gimli-rs/addr2line?branch=master)
7
8A cross-platform library for retrieving per-address debug information
9from files with DWARF debug information.
10
11`addr2line` uses [`gimli`](https://github.com/gimli-rs/gimli) to parse
12the debug information, and exposes an interface for finding
13the source file, line number, and wrapping function for instruction
14addresses within the target program. These lookups can either be
15performed programmatically through `Context::find_location` and
16`Context::find_frames`, or via the included example binary,
17`addr2line` (named and modelled after the equivalent utility from
18[GNU binutils](https://sourceware.org/binutils/docs/binutils/addr2line.html)).
19
20# Quickstart
21 - Add the [`addr2line` crate](https://crates.io/crates/addr2line) to your `Cargo.toml`
22 - Load the file and parse it with [`addr2line::object::File::parse`](https://docs.rs/object/*/object/struct.File.html#method.parse)
23 - Pass the parsed file to [`addr2line::Context::new` ](https://docs.rs/addr2line/*/addr2line/struct.Context.html#method.new)
24 - Use [`addr2line::Context::find_location`](https://docs.rs/addr2line/*/addr2line/struct.Context.html#method.find_location)
25 or [`addr2line::Context::find_frames`](https://docs.rs/addr2line/*/addr2line/struct.Context.html#method.find_frames)
26 to look up debug information for an address
27
28# Performance
29
30`addr2line` optimizes for speed over memory by caching parsed information.
31The DWARF information is parsed lazily where possible.
32
33The library aims to perform similarly to equivalent existing tools such
34as `addr2line` from binutils, `eu-addr2line` from elfutils, and
35`llvm-symbolize` from the llvm project, and in the past some benchmarking
36was done that indicates a comparable performance.
37
38## License
39
40Licensed under either of
41
42 * Apache License, Version 2.0 ([`LICENSE-APACHE`](./LICENSE-APACHE) or http://www.apache.org/licenses/LICENSE-2.0)
43 * MIT license ([`LICENSE-MIT`](./LICENSE-MIT) or http://opensource.org/licenses/MIT)
44
45at your option.
46
47Unless you explicitly state otherwise, any contribution intentionally submitted
48for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
49dual licensed as above, without any additional terms or conditions.
50
){kind=link}
){kind=link}
){kind=link}
){kind=link}