addr2line Rust Library

To quickly use addr2line for looking up debug information from a file, follow these steps:

1. Add the addr2line crate to your Cargo.toml.
2. Initialize a new loader using addr2line::Loader::new(path) with the path to your debug file.
3. Use addr2line::Loader::find_location to retrieve the file name, line number, and function name for an address, or use addr2line::Loader::find_frames to retrieve the call stack.

The addr2line library provides two main ways to perform address-to-line translation:

1. Context (Low-level): Used when you have already parsed DWARF sections (e.g., using the object crate and gimli). You create a Context to cache parsed information for efficient multiple lookups. It is the core engine for finding locations and frames.
2. Loader (High-level): A convenience abstraction that handles the heavy lifting. It internally memory maps files, uses the object crate for parsing, and manages a Context. It is ideal for most users as it also provides find_symbol to use the symbol table instead of DWARF information.

Key Workflow:

• Use Context::from_dwarf if you already have gimli::Dwarf sections.
• Use Loader if you want a managed lifecycle that handles file loading and Mach-O dSYM/split DWARF automatically.

You can customize how addr2line presents information using these combinations:

LLVM Style

To match the output of llvm-symbolizer, use the --llvm flag. This is useful for scripts expecting that specific format.

addr2line -e my_exe 0x401234 --llvm

Pretty Printing

For more readable output where each location is on its own line, use -p or --pretty-print. This is often used in conjunction with -f (functions) and -i (inlines) to see call stacks clearly.

addr2line -e my_exe 0x401234 -p -f -i

Including Addresses

By default, the address is not printed. To include it, use -a or --addresses.

addr2line -e my_exe 0x401234 -a

The addr2line command-line tool translates instruction addresses into file names, line numbers, and function names using debug information (DWARF).

Input Methods

• Command-line arguments: Provide hex addresses directly as arguments.
• Standard Input (stdin): Pipe a list of hex addresses (e.g., from a file or another tool) into the command.
• All addresses: Use the --all flag to display all addresses that contain line number information within the executable.

Basic Usage

# Translate a single address from an executable
addr2line -e my_executable 0x401234

# Translate addresses from stdin
echo "0x401234" | addr2line -e my_executable

# Display all addresses with line info
addr2line -e my_executable --all

# Example: Basic address translation
addr2line -e my_executable 0x401234

You can retrieve the memory range of a specific section by its name using get_section_range.

use addr2line::Loader;

let loader = Loader::new("path/to/executable")?;
if let Some(range) = loader.get_section_range(b".text") {
    println!("Section starts at: 0x{:x}, ends at: 0x{:x}", range.begin, range.end);
}

If your DWARF information is split across multiple files, Context::preload_units allows you to proactively load the necessary data to ensure future lookups for a specific address do not require asynchronous loading.

preload_units returns an iterator of (SplitDwarfLoad, callback) pairs. You must invoke the provided callback with the loaded DWARF data to complete the process.

// Example pattern for preloading split DWARF
ctx.preload_units(ADDRESS).for_each(|(load, callback)| {
    // 1. Load the DWO/split data (implementation specific)
    let dwo = do_split_dwarf_load(load);
    // 2. Pass it to the callback to update the context
    callback(dwo).unwrap();
});

You can initialize a Loader using one of two methods depending on whether you need to provide a supplementary object file.

• new(path): Loads DWARF data for the executable at the specified path.
• new_with_sup(path, sup_path): Loads DWARF data for the executable at path and optionally uses a supplementary object file at sup_path.

use addr2line::Loader;
use std::path::Path;

// Basic initialization
let loader = Loader::new("path/to/executable")?;

// Initialization with a supplementary object file
let loader = Loader::new_with_sup("path/to/executable", Some("path/to/supplementary"))?;