### Setup Benchmark Data and Run Benchmarks

Source: https://github.com/libbpf/blazesym/blob/main/README-devel.md

Performs one-time setup for benchmark data and then runs the benchmark suite. Requires the `nightly` feature and the `has_large_test_files` configuration.

```sh
# Perform one-time setup of required data.
$ cargo check --package blazesym-dev --features=generate-large-test-files
$ RUSTFLAGS='--cfg has_large_test_files' cargo bench --features=nightly
```

--------------------------------

### Get sym-debuginfod Help Information

Source: https://github.com/libbpf/blazesym/blob/main/examples/sym-debuginfod/README.md

Display general usage information for the sym-debuginfod example by running it with the --help flag. This is useful for understanding available options.

```bash
$ cargo run --package sym-debuginfod -- --help
```

--------------------------------

### Cargo.toml Configuration for Tracing

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/module-overview.md

Example of how to enable the 'tracing' feature for the blazesym crate in your Cargo.toml file.

```toml
blazesym = { version = "0.2", features = ["tracing"] }
```

--------------------------------

### Create Process Symbolization Source

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolize-sources.md

Examples of creating a Process symbolization source for the current or a specific process.

```rust
use blazesym::symbolize::source::Process;
use blazesym::symbolize::Source;
use blazesym::Pid;

// Current process
let process_src = Source::Process(Process::new(Pid::Slf));

// Specific process
let process_src = Source::Process(Process::new(Pid::from(12345)));
```

--------------------------------

### Normalizer::new

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/normalize-api.md

Creates a new Normalizer instance with default configuration. This is the simplest way to get started with address normalization.

```APIDOC
## Normalizer::new

### Description
Creates a new `Normalizer` with default configuration.

### Method
`new()`

### Returns
`Self` (a new `Normalizer` instance)

### Example
```rust
use blazesym::normalize::Normalizer;

let normalizer = Normalizer::new();
```
```

--------------------------------

### Perform Fully Static Go Builds

Source: https://github.com/libbpf/blazesym/blob/main/go/README.md

Pass this flag to 'go build' or 'go install' to create a fully static Go binary, which includes statically linked C dependencies.

```bash
-ldflags='-extldflags "-static"'
```

--------------------------------

### Run sym-debuginfod with PID and Addresses

Source: https://github.com/libbpf/blazesym/blob/main/examples/sym-debuginfod/README.md

Execute the sym-debuginfod example with a process ID and memory addresses to retrieve symbol information. Ensure the DEBUGINFOD_URLS environment variable is set.

```bash
$ cargo run --package sym-debuginfod -- 3738900 0x7fd4e762a100 0x7fd4e762d200
```

--------------------------------

### Example Cargo.toml with BlazeSym Features

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/module-overview.md

Demonstrates how to include BlazeSym in your project's dependencies and enable specific features like 'apk', 'gsym', and 'breakpad'.

```toml
[dependencies]
blazesym = { version = "0.2", features = ["apk", "gsym", "breakpad"] }
```

--------------------------------

### Example Usage of NormalizeOpts

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/normalize-api.md

Demonstrates how to instantiate NormalizeOpts with specific configurations. Set `sorted_addrs` to true if addresses are pre-sorted for performance. Enable `apk_to_elf` to normalize APK addresses to contained ELF binaries.

```rust
use blazesym::normalize::NormalizeOpts;

let opts = NormalizeOpts {
    sorted_addrs: true,
    map_files: false,
    #[cfg(feature = "apk")]
    apk_to_elf: true,
    ..Default::default()
};
```

--------------------------------

### Example Usage of Normalizer with UserOutput

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/normalize-api.md

Shows how to normalize user addresses and interpret the results. Use the `meta_index` from `outputs` to retrieve detailed metadata about the binary or APK from the `meta` vector.

```rust
use blazesym::normalize::Normalizer;
use blazesym::Pid;

let normalizer = Normalizer::new();
let addresses = [0x7f5f8e23a790u64];
let result = normalizer.normalize_user_addrs(Pid::Slf, &addresses)?;

assert_eq!(result.outputs.len(), 1);
let (file_offset, meta_idx) = result.outputs[0];
let metadata = &result.meta[meta_idx];

println!("File offset: {:#x}", file_offset);
println!("From binary: {:?}", metadata);
```

--------------------------------

### Configure Process Source without Perf Map

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolize-sources.md

Example of creating a Process source with `perf_map` disabled.

```rust
let mut process = Process::new(Pid::Slf);
process.perf_map = false;
let process_src = Source::Process(process);
```

--------------------------------

### Run All Tests

Source: https://github.com/libbpf/blazesym/blob/main/README-devel.md

Executes the majority of the project's tests using cargo. Requires sudo setup for privileged functionality.

```sh
cargo test --workspace
```

--------------------------------

### Build blazesym-c with Cargo

Source: https://github.com/libbpf/blazesym/blob/main/go/README.md

Use this command to build the blazesym-c library using Cargo. Ensure you have Rust and Cargo installed.

```bash
cargo build --release
```

--------------------------------

### BlazeSym Cargo.toml Configurations

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/README.md

Examples of how to configure BlazeSym dependencies in Cargo.toml for minimal, standard, full-featured, Android-specific, and observability-enhanced builds.

```toml
# Minimal
blazesym = { version = "0.2", default-features = false }
```

```toml
# Standard (recommended)
blazesym = "0.2"
```

```toml
# Full featured
blazesym = { version = "0.2", features = ["apk", "breakpad", "gsym"] }
```

```toml
# Android
blazesym = { version = "0.2", features = ["apk"] }
```

```toml
# With observability
blazesym = { version = "0.2", features = ["tracing"] }
```

--------------------------------

### Configure Process Source without Map Files

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolize-sources.md

Example of creating a Process source with `map_files` disabled, which does not require special privileges.

```rust
let mut process = Process::new(Pid::Slf);
process.map_files = false;
let process_src = Source::Process(process);
```

--------------------------------

### Enable CPU Profiling with cargo-flamegraph

Source: https://github.com/libbpf/blazesym/blob/main/README-devel.md

Generates a CPU profile in flamegraph format for a specific benchmark. Requires `cargo-flamegraph` to be installed and `force-frame-pointers` to be enabled.

```sh
$ RUSTFLAGS="-C force-frame-pointers=yes" cargo flamegraph -o /tmp/flamegraph.svg --cmd 'record -F 997 --call-graph dwarf,64000 -g -o /tmp/perf.dat' --package=blazesym --unit-bench --root --features=nightly -- bench_function_parsing_blazesym
```

```sh
$ RUSTFLAGS="-C force-frame-pointers=yes" cargo flamegraph -o /tmp/flamegraph.svg --cmd 'record -F 997 --call-graph dwarf,64000 -g -o /tmp/perf.dat' --bench=main --root --features=nightly -- symbolize_gsym_multi_no_setup --bench
```

--------------------------------

### Run BlazeCLI from Source

Source: https://github.com/libbpf/blazesym/blob/main/cli/README.md

Execute BlazeCLI directly from a source checkout using 'cargo run'. This is useful for development or testing without installation.

```sh
$ cargo run -p blazecli -- symbolize elf --path /lib64/libc.so.6 00000000000caee0
```

--------------------------------

### Remote Symbolization Workflow Example

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/normalize-api.md

Demonstrates a remote symbolization workflow using blazesym's Normalizer and Symbolizer. This snippet shows how to normalize user addresses on an embedded system and then use the generated metadata to symbolize those addresses on a separate system with access to symbols.

```rust
use blazesym::normalize::Normalizer;
use blazesym::symbolize::{Symbolizer, Input, Source};
use blazesym::symbolize::source::Elf;
use blazesym::Pid;

// On the embedded/locked-down system:
let normalizer = Normalizer::new();
let pid = Pid::Slf;
let addresses = [0x7f5f8e23a790u64, 0x7f5f8e23a800u64];

// Normalize addresses to file offsets
let normalized = normalizer.normalize_user_addrs(pid, &addresses)?;

// Transfer normalized.outputs and normalized.meta to another system...

// On the system with symbols (different machine):
let symbolizer = Symbolizer::new();

for (file_offset, meta_idx) in &normalized.outputs {
    // Reconstruct Source from metadata
    let source = match &normalized.meta[*meta_idx] {
        blazesym::normalize::UserMeta::Elf(elf) => {
            Source::Elf(Elf::new(elf.path.as_ref()))
        }
        _ => continue,
    };

    // Symbolize using file offset
    let result = symbolizer.symbolize_single(
        &source,
        Input::FileOffset(*file_offset)
    )?;

    if let Some(sym) = result.as_sym() {
        println!("Symbol: {}", sym.name);
    }
}
```

--------------------------------

### Handle Out of Memory Error

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/error-handling.md

Provides an example of checking for and handling an `ErrorKind::OutOfMemory` error during a large operation.

```rust
use blazesym::ErrorKind;

match some_large_operation() {
    Err(e) if e.kind() == ErrorKind::OutOfMemory => {
        eprintln!("Out of memory");
        std::process::exit(1);
    }
    Err(e) => eprintln!("Error: {}", e),
    Ok(result) => println!("Success"),
}
```

--------------------------------

### Iterate Over All Symbols in a Binary

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/quick-start.md

List symbols within a binary file. This example shows how to iterate through symbols of an ELF binary and optionally break after a certain count.

```rust
use blazesym::inspect::{Inspector, Source};
use blazesym::inspect::source::Elf;
use std::ops::ControlFlow;

fn main() -> blazesym::Result<()> {
    let inspector = Inspector::new();
    let src = Source::Elf(Elf::new("/usr/bin/ls"));
    
    let mut count = 0;
    inspector.for_each(&src, |sym| {
        println!("{}: {:#x} ({})", sym.name, sym.addr, 
            match sym.sym_type {
                blazesym::SymType::Function => "func",
                blazesym::SymType::Variable => "var",
                _ => "other",
            }
        );
        
        count += 1;
        if count >= 100 {
            ControlFlow::Break(())
        } else {
            ControlFlow::Continue(())
        }
    })?;
    
    Ok(())
}
```

--------------------------------

### Example: Convert Sym to Owned

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/types.md

Demonstrates how to convert a `Sym` instance, which may contain borrowed data, into an owned `Sym<'static>` using the `into_owned` method. This ensures that the data remains valid beyond the original scope.

```rust
use blazesym::symbolize::Symbolizer;
use blazesym::Pid;

let symbolizer = Symbolizer::new();
// ... after symbolization ...
let sym = /* Sym result */;
let owned = sym.into_owned();  // All Cow types become owned
```

--------------------------------

### Recover from Errors with Fallback

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/error-handling.md

This example demonstrates how to recover from specific errors, such as `ErrorKind::NotFound`, by providing a fallback mechanism. If the primary symbolization source fails, it attempts to use an alternative source.

```rust
use blazesym::ErrorKind;

fn symbolize_with_fallback(primary: &str, fallback: &str) -> blazesym::Result<Vec<_>> {
    use blazesym::symbolize::{Symbolizer, Source};
    use blazesym::symbolize::source::Elf;
    
    let symbolizer = Symbolizer::new();
    let src = Source::Elf(Elf::new(primary));
    let input = blazesym::symbolize::Input::AbsAddr(&[0x1000]);
    
    match symbolizer.symbolize(&src, input) {
        Ok(results) => Ok(results),
        Err(e) if e.kind() == ErrorKind::NotFound => {
            // Fall back to alternative source
            let src = Source::Elf(Elf::new(fallback));
            symbolizer.symbolize(&src, input)
        }
        Err(e) => Err(e),
    }
}
```

--------------------------------

### Build a Normalizer with custom options

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/normalize-api.md

Constructs a `Normalizer` instance using a builder pattern, allowing fine-grained control over its configuration. This example demonstrates enabling build ID reading and explicitly disabling VMA caching.

```rust
use blazesym::normalize::Normalizer;

let normalizer = Normalizer::builder()
    .enable_build_ids(true)
    .enable_vma_caching(false)
    .build();
```

--------------------------------

### Setting a Custom APK Dispatcher

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/custom-resolvers.md

Configure a custom dispatcher for APK member symbolization when building a `Symbolizer`. This example shows how to set a dispatcher that prints the member path being processed.

```rust
#[cfg(feature = "apk")]
use blazesym::symbolize::{Symbolizer, ApkDispatch, ApkMemberInfo};

#[cfg(feature = "apk")]
fn create_apk_symbolizer() -> Symbolizer {
    let dispatcher = |info: ApkMemberInfo<'_>| -> blazesym::Result<Option<Box<dyn blazesym::symbolize::Resolve>>> {
        println!("Processing APK member: {{:?}}", info.member_path);
        Ok(None)  // Use default
    };
    
    Symbolizer::builder()
        .set_apk_dispatcher(dispatcher)
        .build()
}
```

--------------------------------

### Symbolize Kernel Addresses

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/quick-start.md

Resolve kernel-space addresses to symbol names. This example uses absolute addresses.

```rust
use blazesym::symbolize::{Symbolizer, Input, Source};
use blazesym::symbolize::source::Kernel;

fn main() -> blazesym::Result<()> {
    let symbolizer = Symbolizer::new();
    let src = Source::Kernel(Kernel::default());
    
    // Kernel addresses (absolute)
    let addresses = [0xffffffff81000000u64];
    let results = symbolizer.symbolize(&src, Input::AbsAddr(&addresses))?;
    
    for result in results {
        if let Some(sym) = result.as_sym() {
            println!("Kernel symbol: {}", sym.name);
        }
    }
    
    Ok(())
}
```

--------------------------------

### Setting a Custom Process Dispatcher

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/custom-resolvers.md

Configure a custom dispatcher for process memory symbolization when building a `Symbolizer`. This example demonstrates setting a dispatcher that logs the memory range being dispatched.

```rust
use blazesym::symbolize::{Symbolizer, ProcessDispatch, ProcessMemberInfo};
use blazesym::Result;

fn create_custom_symbolizer() -> Symbolizer {
    let dispatcher = |info: ProcessMemberInfo<'_>| -> Result<Option<Box<dyn blazesym::symbolize::Resolve>>> {
        // Custom dispatch logic
        println!("Dispatching for range: {{:x?}}", info.range);
        Ok(None)  // Use default for now
    };
    
    Symbolizer::builder()
        .set_process_dispatcher(dispatcher)
        .build()
}
```

--------------------------------

### Normalize user-space addresses with custom options

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/normalize-api.md

Normalizes user-space addresses using a `Normalizer` instance with custom options applied via `NormalizeOpts`. This example shows how to pre-sort addresses and disable the use of `map_files` in favor of symbolic paths.

```rust
use blazesym::normalize::{Normalizer, NormalizeOpts};
use blazesym::Pid;

let normalizer = Normalizer::new();
let mut opts = NormalizeOpts::default();
opts.sorted_addrs = true;  // If addresses are pre-sorted
opts.map_files = false;     // Use symbolic paths instead of map_files

let addresses = [0x1000, 0x2000, 0x3000];  // Pre-sorted
let result = normalizer.normalize_user_addrs_with_opts(
    Pid::Slf,
    &addresses,
    &opts
)?;
```

--------------------------------

### Get Code Location Information

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/quick-start.md

Retrieves symbol name, source file path, and line number for a given virtual offset. Also shows how to access information about inlined functions.

```rust
use blazesym::symbolize::{Symbolizer, Input, Source};
use blazesym::symbolize::source::Elf;

fn main() -> blazesym::Result<()> {
    // Enable code_info by default when creating symbolizer
    let symbolizer = Symbolizer::new();
    let src = Source::Elf(Elf::new("/usr/bin/bash"));
    
    let result = symbolizer.symbolize_single(&src, Input::VirtOffset(0x1000))?;
    
    if let Some(sym) = result.as_sym() {
        println!("Symbol: {}", sym.name);
        
        if let Some(code_info) = &sym.code_info {
            println!("File: {}", code_info.to_path().display());
            if let Some(line) = code_info.line {
                println!("Line: {}", line);
            }
        }
        
        // Inlined functions
        for inlined in sym.inlined.iter() {
            println!("Inlined: {}", inlined.name);
        }
    }
    
    Ok(())
}
```

--------------------------------

### Custom APK Dispatcher Implementation

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/custom-resolvers.md

Implement the `ApkDispatch` trait to create a custom dispatcher for APK members. This example shows how to conditionally use a default resolver or a custom one based on the member path.

```rust
#[cfg(feature = "apk")]
use blazesym::symbolize::{ApkDispatch, ApkMemberInfo};

#[cfg(feature = "apk")]
fn my_apk_dispatcher(info: ApkMemberInfo<'_>) -> blazesym::Result<Option<Box<dyn blazesym::symbolize::Resolve>>> {
    // Check if we want custom handling for this APK member
    if info.member_path.to_string_lossy().contains("ignored") {
        return Ok(None);  // Use default
    }
    
    // Custom resolver for this APK member
    let resolver = create_apk_resolver(&info)?;
    Ok(Some(Box::new(resolver)))
}

#[cfg(feature = "apk")]
fn create_apk_resolver(info: &ApkMemberInfo<'_>) -> blazesym::Result<Box<dyn blazesym::symbolize::Resolve>> {
    todo!()
}
```

--------------------------------

### Creating an APK Source

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

Instantiate a `Source::Apk` using `Apk::new` when the 'apk' feature is enabled.

```rust
Source::Apk(Apk::new(...))
```

--------------------------------

### Run All Tests

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

Execute all unit and integration tests for the library. This is the most basic test command.

```bash
cargo test
```

--------------------------------

### Generate Documentation

Source: https://github.com/libbpf/blazesym/blob/main/README-devel.md

Generates project documentation in the format that will appear on docs.rs. The `--open` flag will automatically open the documentation in a web browser.

```sh
RUSTDOCFLAGS='--cfg docsrs' cargo doc --open --features="apk,backtrace,breakpad,demangle,dwarf,gsym"
```

--------------------------------

### Configure CGO for blazesym-c

Source: https://github.com/libbpf/blazesym/blob/main/go/README.md

Set these environment variables to inform Go where to find the blazesym-c headers and libraries during the build process.

```bash
CGO_CFLAGS="-I/path/to/blazesym/capi/include" CGO_LDFLAGS="-L/path/to/blazesym/target/release"
```

--------------------------------

### Remote Symbolization - Server Side

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/README.md

Symbolizes addresses on the server using file offsets. This is the counterpart to the device-side normalization in a remote symbolization setup.

```rust
let results = symbolizer.symbolize(&src, Input::FileOffset(&offsets))?;
```

--------------------------------

### Creating a Breakpad Source

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

Instantiate a `Source::Breakpad` using `Breakpad::new` when the 'breakpad' feature is enabled.

```rust
Source::Breakpad(Breakpad::new(...))
```

--------------------------------

### Configure Kernel Symbolization Source with MaybeDefault

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolize-sources.md

Demonstrates configuring a Kernel symbolization source using the MaybeDefault enum for optional settings. This allows fine-grained control over vmlinux, kallsyms, and KASLR offset.

```rust
use blazesym::symbolize::source::Kernel;
use blazesym::MaybeDefault;

let mut kernel = Kernel::default();
kernel.vmlinux = MaybeDefault::None;        // Disable vmlinux
kernel.kallsyms = MaybeDefault::Default;    // Auto-detect
kernel.kaslr_offset = Some(0x1000);         // Manual KASLR offset
```

--------------------------------

### Process Constructor

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolize-sources.md

Creates a new Process symbolization source with default settings.

```rust
pub fn new(pid: Pid) -> Self
```

--------------------------------

### Normalizer Configuration in Rust

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/module-overview.md

Shows how to configure a Normalizer instance, with options for process map querying, virtual memory address caching, and build ID extraction.

```rust
let normalizer = Normalizer::builder()
    .enable_procmap_query(true)
    .enable_vma_caching(false)
    .enable_build_ids(true)
    .build();
```

--------------------------------

### Symbolizer Configuration in Rust

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/module-overview.md

Demonstrates how to build a Symbolizer instance with various options enabled, including auto-reloading, code info, inlined functions, demangling, and custom debug directories.

```rust
let symbolizer = Symbolizer::builder()
    .enable_auto_reload(true)
    .enable_code_info(true)
    .enable_inlined_fns(true)
    .enable_demangling(true)
    .set_debug_dirs(Some(vec!["/path/to/debug"]))
    .build();
```

--------------------------------

### Creating a Gsym File Source

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

Instantiate a `Source::Gsym` using `GsymFile::new` when the 'gsym' feature is enabled.

```rust
Source::Gsym(GsymFile::new(...))
```

--------------------------------

### CodeInfo to_path Method

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/types.md

Combines the directory and file fields to construct the full path to the source file.

```rust
pub fn to_path(&self) -> Cow<'_, Path>
```

--------------------------------

### Create a new Normalizer with default configuration

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/normalize-api.md

Instantiates a `Normalizer` using default settings. These defaults include parsing `/proc/<pid>/maps`, disabling VMA caching, enabling build ID reading, and disabling build ID caching.

```rust
use blazesym::normalize::Normalizer;

let normalizer = Normalizer::new();
```

--------------------------------

### Handle Common Error Cases

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/quick-start.md

Demonstrates how to handle specific errors like file not found, permission denied, or invalid binary format when symbolizing.

```rust
use blazesym::symbolize::{Symbolizer, Input, Source};
use blazesym::symbolize::source::Elf;
use blazesym::ErrorKind;

fn main() {
    let symbolizer = Symbolizer::new();
    let src = Source::Elf(Elf::new("/nonexistent/file.so"));
    
    match symbolizer.symbolize_single(&src, Input::AbsAddr(0x1000)) {
        Ok(result) => {
            if let Some(sym) = result.as_sym() {
                println!("Found: {}", sym.name);
            }
        }
        Err(e) => match e.kind() {
            ErrorKind::NotFound => eprintln!("Binary not found"),
            ErrorKind::PermissionDenied => eprintln!("Permission denied"),
            ErrorKind::InvalidData => eprintln!("Invalid binary format"),
            _ => eprintln!("Error: {:?}", e.kind()),
        }
    }
}
```

--------------------------------

### Propagate Errors with '?'

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/error-handling.md

This example demonstrates how to propagate errors using the `?` operator in Rust. It defines a function `symbolize_address` that returns a `blazesym::Result` and uses `?` to automatically return early if an error occurs during symbolization.

```rust
use blazesym::symbolize::Symbolizer;

fn symbolize_address(addr: u64) -> blazesym::Result<String> {
    let symbolizer = Symbolizer::new();
    let src = blazesym::symbolize::Source::Elf(
        blazesym::symbolize::source::Elf::new("/usr/lib64/libc.so.6")
    );
    
    let result = symbolizer.symbolize_single(&src, 
        blazesym::symbolize::Input::AbsAddr(addr))?;  // ? propagates error
    
    match result {
        blazesym::symbolize::Symbolized::Sym(sym) => Ok(sym.name.to_string()),
        blazesym::symbolize::Symbolized::Unknown(_) => Ok("unknown".to_string()),
    }
}
```

--------------------------------

### FindSymOpts Enum

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/types.md

Controls the level of detail for symbol data retrieval. Use Basic for minimal information, CodeInfo to include source location, and CodeInfoAndInlined to also get inlined function details.

```rust
pub enum FindSymOpts {
    Basic,
    CodeInfo,
    CodeInfoAndInlined,
}
```

--------------------------------

### Creating and Configuring Elf Symbolization Sources

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolize-sources.md

Demonstrates how to create an Elf symbolization source and optionally disable the use of DWARF debug symbols.

```rust
use blazesym::symbolize::source::Elf;
use blazesym::symbolize::Source;

let elf_src = Source::Elf(Elf::new("/usr/lib64/libc.so.6"));
let mut elf = Elf::new("/lib64/ld-linux-x86-64.so.2");
elf.debug_syms = false;  // Use only ELF symbols, not DWARF
let elf_src = Source::Elf(elf);
```

--------------------------------

### Run Tests with All Features

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

Execute all tests while enabling every feature of the library. Useful for comprehensive testing.

```bash
cargo test --all-features
```

--------------------------------

### Custom Process Dispatcher Implementation Pattern

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/custom-resolvers.md

Illustrates how to implement a custom process dispatcher function. It shows how to inspect ProcessMemberInfo and conditionally return None for default handling or Some(resolver) for custom symbolization.

```rust
use blazesym::symbolize::{ProcessDispatch, ProcessMemberInfo};
use blazesym::Result;
use std::path::Path;

fn my_process_dispatcher(info: ProcessMemberInfo<'_>) -> Result<Option<Box<dyn blazesym::symbolize::Resolve>>> {
    // Inspect the member information
    let range = &info.range;
    
    // Return None to use the default dispatcher
    if should_use_default(info.member_entry) {
        return Ok(None);
    }
    
    // Or return Some(resolver) for custom handling
    let resolver = create_custom_resolver(info)?;
    Ok(Some(Box::new(resolver)))
}

fn should_use_default(entry: &blazesym::maps::PathName) -> bool {
    // Custom logic to determine when to use defaults
    false
}

fn create_custom_resolver(info: ProcessMemberInfo<'_>) -> Result<Box<dyn blazesym::symbolize::Resolve>> {
    // Create and return custom resolver
    todo!()
}
```

--------------------------------

### Symbolize Address using Process Source

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/module-overview.md

Demonstrates how to use the Symbolizer to convert an absolute address to symbol information from the current running process. Ensure the necessary imports are included.

```rust
use blazesym::symbolize::{Symbolizer, Input, Source};
use blazesym::symbolize::source::Process;
use blazesym::Pid;

let symbolizer = Symbolizer::new();
let src = Source::Process(Process::new(Pid::Slf));
let addrs = [0x7f5f8e23a790u64];
let results = symbolizer.symbolize(&src, Input::AbsAddr(&addrs))?;

for result in results {
    if let Some(sym) = result.as_sym() {
        println!("Symbol: {} at {:#x}", sym.name, sym.addr);
    }
}
```

--------------------------------

### Create Breakpad Symbolization Source

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolize-sources.md

Instantiates a Breakpad symbolization source using a file path. This source supports symbol size, source code location, and inlined function information.

```rust
use blazesym::symbolize::source::Breakpad;
use blazesym::symbolize::Source;

let breakpad_src = Source::Breakpad(Breakpad::new("/path/to/symbols.sym"));
```

--------------------------------

### Creating a Gsym Data Source

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

Instantiate a `Source::Gsym` using `GsymData::new` when the 'gsym' feature is enabled.

```rust
Source::Gsym(GsymData::new(...))
```

--------------------------------

### Minimal BlazeSym Configuration (ELF only)

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

Use this configuration for minimal dependencies, focusing solely on ELF symbols without DWARF support or symbol demangling.

```toml
blazesym = { version = "0.2", default-features = false, features = [] }
```

--------------------------------

### List All Symbols with Details

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/inspect-api.md

Iterates over all symbols in an ELF library using `for_each` and prints their name, address, and size. Note that demangling must be done manually.

```rust
use blazesym::inspect::{Inspector, Source};
use blazesym::inspect::source::Elf;
use std::ops::ControlFlow;

let inspector = Inspector::new();
let src = Source::Elf(Elf::new("/usr/lib64/libstdc++.so.6"));

inspector.for_each(&src, |sym| {
    // Note: Inspector doesn't demangle automatically.
    // You must demangle manually if needed using rustc-demangle or cpp_demangle.
    println!("{}: {:#x} (size: {:?})", sym.name, sym.addr, sym.size);
    
    ControlFlow::Continue(())
})?;
```

--------------------------------

### Inspector Initialization in Rust

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/module-overview.md

Illustrates the basic initialization of an Inspector, which caches parsed data for its lifetime.

```rust
let inspector = Inspector::new();
// Caches parsed data for the inspector's lifetime
```

--------------------------------

### Registering and Reusing an ELF Resolver

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/custom-resolvers.md

Demonstrates how to create an ElfResolver, register it with the Symbolizer for a specific path, and how subsequent symbolization calls will reuse the cached resolver. This is useful for optimizing symbolization when dealing with frequently accessed shared libraries.

```rust
use blazesym::symbolize::Symbolizer;
use blazesym::helper::ElfResolver;
use std::path::Path;
use std::rc::Rc;

fn main() -> blazesym::Result<()> {
    let mut symbolizer = Symbolizer::new();
    
    // Create a resolver outside the symbolizer
    let resolver = Rc::new(ElfResolver::open(Path::new("/usr/lib64/libc.so.6"))?);
    
    // Register it for reuse
    symbolizer.register_elf_resolver(Path::new("/usr/lib64/libc.so.6"), resolver)?;
    
    // Subsequent symbolization will reuse the registered resolver
    Ok(())
}
```

--------------------------------

### Standard BlazeSym Configuration (with debug info)

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

This configuration enables default features, including ELF and DWARF symbol support, symbol demangling, and backtrace capture capabilities.

```toml
blazesym = { version = "0.2" }  # Uses defaults
```

--------------------------------

### Handle File Not Found Error

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/error-handling.md

Demonstrates how to catch a `ErrorKind::NotFound` error when attempting to symbolize a non-existent file.

```rust
use blazesym::symbolize::{Symbolizer, Source};
use blazesym::symbolize::source::Elf;
use blazesym::ErrorKind;

let symbolizer = Symbolizer::new();
let src = Source::Elf(Elf::new("/nonexistent/file.so"));

match symbolizer.symbolize_single(&src, blazesym::symbolize::Input::AbsAddr(0x1000)) {
    Err(e) if e.kind() == ErrorKind::NotFound => {
        println!("Binary file not found");
    }
    Ok(result) => println!("Symbolization succeeded"),
    Err(e) => println!("Unexpected error: {:?}", e.kind()),
}
```

--------------------------------

### Run Integration Tests

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

Execute only the integration tests. These tests are typically located in the `tests` directory.

```bash
cargo test --test integration
```

--------------------------------

### Full BlazeSyml for System Profiler (Linux)

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

This configuration enables all default features for full Linux support, including kernel symbol handling.

```toml
# Full Linux support including kernel
blazesym = { version = "0.2" }  # All defaults
```

--------------------------------

### NormalizeOpts Structure

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/normalize-api.md

Defines options for controlling the address normalization process. Use this to configure sorting, map file usage, and APK to ELF normalization.

```rust
pub struct NormalizeOpts {
    pub sorted_addrs: bool,
    pub map_files: bool,
    #[cfg(feature = "apk")]
    pub apk_to_elf: bool,
}
```

--------------------------------

### BlazeSyml with Tracing for Cloud/Observability

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

Enable tracing integration for cloud and observability use cases.

```toml
# With tracing integration
blazesym = { version = "0.2", features = ["tracing"] }
```

--------------------------------

### Create Gsym File Symbolization Source

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolize-sources.md

Instantiates a file-based Gsym symbolization source. This source is optimized for fast lookups and reduced file size, supporting symbol size, source code location, and inlined function information.

```rust
use blazesym::symbolize::source::GsymFile;
use blazesym::symbolize::Source;

let gsym_src = Source::Gsym(GsymFile::new("/path/to/binary.gsym").into());
```

--------------------------------

### Set Runtime Library Path

Source: https://github.com/libbpf/blazesym/blob/main/go/README.md

Ensure the blazesym-c shared library is discoverable at runtime by setting the LD_LIBRARY_PATH environment variable.

```bash
LD_LIBRARY_PATH=/path/to/blazesym/target/release
```

--------------------------------

### Kernel Symbolization Source Defaults

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolize-sources.md

Instantiate the Kernel symbolization source using default auto-detection for vmlinux and kallsyms.

```rust
use blazesym::symbolize::source::Kernel;
use blazesym::symbolize::Source;
use blazesym::MaybeDefault;

// Use defaults (auto-detect vmlinux and kallsyms)
let kernel_src = Source::Kernel(Kernel::default());
```

--------------------------------

### BlazeSyml with Breakpad for JVM/Profiler Integration

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

Enable Breakpad support for exported profiling data when integrating with JVM or profilers.

```toml
# With Breakpad support for exported profiling data
blazesym = { version = "0.2", features = ["breakpad"] }
```

--------------------------------

### Configure Symbolizer for Maximum Detail

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/README.md

Enable source locations, inlined functions, name demangling, and auto-reloading of changed files for detailed symbolization.

```rust
let symbolizer = Symbolizer::builder()
    .enable_code_info(true)          // Source locations
    .enable_inlined_fns(true)        // Inlined functions
    .enable_demangling(true)         // Demangle names
    .enable_auto_reload(true)        // Auto-reload changed files
    .build();
```

--------------------------------

### NormalizeOpts

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/normalize-api.md

Options to control the address normalization process. Allows customization of sorting, map file usage, and APK to ELF conversion.

```APIDOC
## NormalizeOpts

Options controlling the normalization process.

### Fields
- **sorted_addrs** (bool) - Optional - Addresses are pre-sorted in ascending order. Set to `true` if your addresses are already sorted to skip internal sorting and improve performance.
- **map_files** (bool) - Optional - Report `/proc/<pid>/map_files/` paths. If `true`, use `/proc/<pid>/map_files/` (requires `SYS_ADMIN`). If `false`, use symbolic paths from `/proc/<pid>/maps` (any process).
- **apk_to_elf** (bool) - Optional - Normalize APK addresses to contained ELF. If `true`, addresses in APK members become offsets into the contained ELF, reporting `Elf` metadata instead of `Apk`. Useful for consistent symbolization across APK and standalone binaries.

### Example
```rust
use blazesym::normalize::NormalizeOpts;

let opts = NormalizeOpts {
    sorted_addrs: true,
    map_files: false,
    #[cfg(feature = "apk")]
    apk_to_elf: true,
    ..Default::default()
};
```
```

--------------------------------

### Handle Permission Denied Error for Process Symbolization

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/error-handling.md

Shows how to handle a `ErrorKind::PermissionDenied` error when trying to symbolize a process without sufficient privileges.

```rust
use blazesym::symbolize::{Symbolizer, Source};
use blazesym::symbolize::source::Process;
use blazesym::ErrorKind;
use blazesym::Pid;

let symbolizer = Symbolizer::new();
let mut process = Process::new(Pid::from(1));  // PID 1 (init)

match symbolizer.symbolize(&Source::Process(process), 
    blazesym::symbolize::Input::AbsAddr(&[0x1000])) {
    Err(e) if e.kind() == ErrorKind::PermissionDenied => {
        println!("Cannot access PID 1 - need elevated privileges");
    }
    Ok(_) => println!("Success"),
    Err(e) => println!("Error: {:?}", e.kind()),
}
```

--------------------------------

### Enable Static Linking for blazesym-c

Source: https://github.com/libbpf/blazesym/blob/main/go/README.md

Add these flags to CGO_LDFLAGS to statically link against the blazesym-c library, avoiding the need for a separate shared library at runtime.

```bash
-Wl,-Bstatic -lblazesym_c -Wl,-Bdynamic
```

--------------------------------

### BlazeSyml for Maximum Cross-Platform Support

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

Enable maximum format support for cross-platform development, including APK, Breakpad, and gsym.

```toml
# Maximum format support
blazesym = { version = "0.2", features = ["apk", "breakpad", "gsym"] }
```

--------------------------------

### Breakpad Source

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolize-sources.md

Represents a symbolization source using Breakpad symbol files. It requires a path to the `.sym` file.

```APIDOC
## Breakpad Source

### Description
Symbolization source for Breakpad symbol files. This allows you to load symbols from `.sym` files.

### Constructor
```rust
pub fn new(path: impl Into<PathBuf>) -> Self
```

Creates a Breakpad source by providing the path to the symbol file.

### Fields
- **path** (`PathBuf`) - Required - Path to the `.sym` Breakpad symbol file

### Features Supported
- Symbol size information
- Source code location information
- Inlined function information

### Example
```rust
use blazesym::symbolize::source::Breakpad;
use blazesym::symbolize::Source;

let breakpad_src = Source::Breakpad(Breakpad::new("/path/to/symbols.sym"));
```
```

--------------------------------

### Run Tests with Tracing Enabled

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

Execute tests while enabling the `tracing` feature. This allows for observability events to be emitted during testing.

```bash
cargo test --features tracing
```

--------------------------------

### Main Entry Points for blazesym

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/INDEX.md

These are the primary structs to interact with for symbolization, normalization, and inspection functionalities in blazesym.

```rust
crate::symbolize::Symbolizer
crate::normalize::Normalizer
crate::inspect::Inspector
```

--------------------------------

### Configure Normalizer with Build IDs and Caching Disabled

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/README.md

Enable build IDs for normalization but disable virtual memory area (VMA) caching for specific use cases.

```rust
let normalizer = Normalizer::builder()
    .enable_build_ids(true)          // Include build IDs
    .enable_vma_caching(false)       // Don't cache VMAs
    .build();
```

--------------------------------

### Build a configured Symbolizer

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolizer-api.md

Constructs a Symbolizer instance using a builder pattern, allowing specific features like code information and symbol demangling to be enabled. This is useful for creating a Symbolizer with a customized set of options.

```rust
use blazesym::symbolize::Symbolizer;

let symbolizer = Symbolizer::builder()
    .enable_code_info(true)
    .enable_demangling(true)
    .build();
```

--------------------------------

### Builder::build

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolizer-api.md

Creates the configured Symbolizer instance based on the builder's settings. This method finalizes the configuration and returns the ready-to-use Symbolizer object.

```APIDOC
## Builder::build

### Description
Create the configured `Symbolizer` instance.

### Method

```rust
pub fn build(self) -> Symbolizer
```

### Example

```rust
use blazesym::symbolize::Symbolizer;

let symbolizer = Symbolizer::builder()
    .enable_code_info(true)
    .enable_demangling(true)
    .build();
```
```

--------------------------------

### Elf Constructor

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolize-sources.md

Creates an Elf source with `debug_syms` set to `true` by default.

```rust
pub fn new(path: impl Into<PathBuf>) -> Self
```

--------------------------------

### Minimal BlazeSyml for Embedded Systems

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

Use this configuration for minimal embedded systems, enabling only ELF symbol lookup and demangling.

```toml
# Minimal: just ELF symbol lookup
blazesym = { version = "0.2", default-features = false, features = ["demangle"] }
```

--------------------------------

### Symbolizer::new

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolizer-api.md

Creates a new Symbolizer with default configuration. This includes enabling automatic reload of symbolization sources, code location information, inlined function reporting, and symbol name demangling, with default debug directories set to `/usr/lib/debug` and `/lib/debug/`.

```APIDOC
## Symbolizer::new

### Description
Creates a new `Symbolizer` with default configuration.

- Enables automatic reload of symbolization sources
- Enables code location information (line numbers, files)
- Enables inlined function reporting
- Enables symbol name demangling
- Sets default debug directories to `/usr/lib/debug` and `/lib/debug/`

### Method

```rust
pub fn new() -> Self
```

### Example

```rust
use blazesym::symbolize::Symbolizer;

let symbolizer = Symbolizer::new();
```
```

--------------------------------

### Create a new Symbolizer

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolizer-api.md

Creates a new Symbolizer instance with default configurations. This includes enabling automatic source reloading, code location information, inlined function reporting, symbol name demangling, and setting default debug directories.

```rust
use blazesym::symbolize::Symbolizer;

let symbolizer = Symbolizer::new();
```

--------------------------------

### Create Apk Symbolization Source

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolize-sources.md

Instantiates an Apk symbolization source. Use this when you need to symbolize addresses within an Android application package (APK). The constructor defaults to using DWARF debug info if available.

```rust
use blazesym::symbolize::source::Apk;
use blazesym::symbolize::Source;

let apk_src = Source::Apk(Apk::new("/path/to/app.apk"));
```

--------------------------------

### Create Breakpad Inspection Source

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/inspect-api.md

Use this to inspect symbols from a Breakpad symbol file. Note that this source has limitations, such as no variable symbol support.

```rust
use blazesym::inspect::source::Breakpad;
use blazesym::inspect::Source;

let src = Source::Breakpad(Breakpad::new("/path/to/symbols.sym"));
```

--------------------------------

### Configure Symbolizer for Maximum Performance

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/README.md

Disable source locations, name demangling, and auto-reloading to optimize symbolizer performance.

```rust
let symbolizer = Symbolizer::builder()
    .enable_code_info(false)         // Skip source locations
    .enable_demangling(false)        // Don't demangle
    .enable_auto_reload(false)       // Skip checking for changes
    .build();
```

--------------------------------

### Process Struct Definition

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/symbolize-sources.md

Defines the configuration options for the Process symbolization source.

```rust
pub struct Process {
    pub pid: Pid,
    pub debug_syms: bool,
    pub perf_map: bool,
    pub map_files: bool,
    pub vdso: bool,
}
```

--------------------------------

### Builder Methods

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/normalize-api.md

Methods available on the Builder to configure the Normalizer. These methods allow enabling or disabling features like PROCMAP_QUERY ioctl, VMA caching, and build ID reading/caching.

```APIDOC
## Builder Methods

### `enable_procmap_query`

#### Description
Use the `PROCMAP_QUERY` ioctl instead of parsing `/proc/<pid>/maps`.

#### Parameters
- **enable** (bool) - Optional - Whether to use the ioctl. Defaults to `false`.

#### Requirements
- Linux kernel 6.11 or higher
- Kernel 6.12+ recommended for complete build ID support

#### Returns
`Self` for method chaining.

--- 

### `enable_vma_caching`

#### Description
Cache VMA ranges and metadata for repeated normalization.

#### Parameters
- **enable** (bool) - Optional - Whether to cache VMAs. Defaults to `false`.

#### Warnings
- Not recommended for general use
- Cannot detect when new mappings are added after caching
- Useful only when process is stable and normalization will be repeated

#### Returns
`Self` for method chaining.

--- 

### `enable_build_ids`

#### Description
Read build IDs from binaries (GNU Build ID).

#### Parameters
- **enable** (bool) - Optional - Whether to read build IDs. Defaults to `true`.

#### Notes
Build ID read failures are swallowed and don't cause normalization to fail.

#### Returns
`Self` for method chaining.

--- 

### `enable_build_id_caching`

#### Description
Cache the build IDs that are read.

#### Parameters
- **enable** (bool) - Optional - Whether to cache build IDs. Defaults to `false`.

#### Notes
Only meaningful when `enable_build_ids` is also `true`.

#### Returns
`Self` for method chaining.

--- 

### `build`

#### Description
Create the configured `Normalizer` instance.

#### Returns
`Normalizer`

#### Example
```rust
use blazesym::normalize::Normalizer;

let normalizer = Normalizer::builder()
    .enable_build_ids(true)
    .enable_vma_caching(false)
    .build();
```
```

--------------------------------

### Symbolizer with APK Dispatcher

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/feature-matrix.md

Configure a Symbolizer to use an APK dispatcher by calling `set_apk_dispatcher` on the builder. This requires the 'apk' feature.

```rust
Symbolizer::builder()
    .set_apk_dispatcher(dispatcher)
    .build()
```

--------------------------------

### Basic Symbolization

Source: https://github.com/libbpf/blazesym/blob/main/_autodocs/module-overview.md

Symbolize virtual offsets from an ELF file. Ensure the ELF file path is correct.

```rust
let symbolizer = Symbolizer::new();
let src = Source::Elf(Elf::new("/usr/lib64/libc.so.6"));
let results = symbolizer.symbolize(&src, Input::VirtOffset(&[0x77790]))?;
```