Relink

https://github.com/weizhiao/relink
Admin
Relink is a high-performance, no_std-friendly ELF loader and runtime linker for Rust enabling plugin...
Tokens:21,167
Snippets:158
Trust Score:8.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install Rust and Run Tests

Source: https://github.com/weizhiao/relink/blob/main/CONTRIBUTING.md

Installs the stable Rust toolchain and runs the project's tests. This is a typical setup for regular development.

```bash
rustup toolchain install stable
cargo test
```

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

### Run a Specific Crate Example

Source: https://github.com/weizhiao/relink/blob/main/CONTRIBUTING.md

Executes an example from a specific crate, such as the `windows-elf-loader`. This is useful for testing platform-specific code.

```bash
cargo run -p windows-elf-loader --example from_memory
```

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

### Install mini-loader for x86_64

Source: https://github.com/weizhiao/relink/blob/main/crates/mini-loader/README.md

Use this command to install the mini-loader for the x86_64 architecture. Ensure you have Rust and Cargo installed.

```shell
$ cargo install mini-loader --target x86_64-unknown-none
```

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

### Execute a file with mini-loader

Source: https://github.com/weizhiao/relink/blob/main/crates/mini-loader/README.md

Demonstrates how to load and execute an ELF file, such as '/bin/ls', using the installed mini-loader.

```shell
$ mini-loader /bin/ls
```

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

### Install mini-loader for riscv64

Source: https://github.com/weizhiao/relink/blob/main/crates/mini-loader/README.md

Install the mini-loader for the riscv64 architecture. Similar to aarch64, this requires specific RUSTFLAGS for PIE support.

```shell
$ RUSTFLAGS="-C relocation-model=pic -C link-arg=-pie" cargo install mini-loader --target riscv64gc-unknown-none-elf
```

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

### Create a Default Loader and Load a Dylib

Source: https://context7.com/weizhiao/relink/llms.txt

Instantiate a default Loader and use it to load a shared object. The loaded dylib must be relocated before use. This example demonstrates loading, relocating, and calling a symbol.

```rust
use elf_loader::{Loader, Result};

fn main() -> Result<()> {
    // Simplest possible setup: load, relocate, call a symbol
    let mut loader = Loader::new();
    let lib = loader
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .relocate()?;

    let f = unsafe { lib.get::<fn() -> i32>("compute").unwrap() };
    println!("compute() = {}", f());
    Ok(())
}
```

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

### Rust Load Dynamic Library and Call Symbol

Source: https://github.com/weizhiao/relink/blob/main/README_zh.md

This example shows how to load a dynamic library, provide a host function for symbol resolution, and then call a function exported by the library. Ensure the 'full' feature is enabled for advanced capabilities.

```rust
use elf_loader::{Loader, Result};

extern "C" fn host_double(value: i32) -> i32 {
    value * 2
}

fn main() -> Result<()> {
    let lib = Loader::new()
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .pre_find_fn(|name| {
            if name == "host_double" {
                Some(host_double as *const ())
            } else {
                None
            }
        })
        .relocate()?;

    let run = unsafe {
        lib.get::<extern "C" fn(i32) -> i32>("run")
            .expect("symbol `run` not found")
    };
    assert_eq!(run(21), 42);

    Ok(())
}
```

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

### Install mini-loader for aarch64

Source: https://github.com/weizhiao/relink/blob/main/crates/mini-loader/README.md

Install the mini-loader for the aarch64 architecture. This command requires specific RUSTFLAGS to enable Position-Independent Executable support.

```shell
$ RUSTFLAGS="-C relocation-model=pic -C link-arg=-pie" cargo install mini-loader --target aarch64-unknown-none
```

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

### Conventional Commit Message Examples

Source: https://github.com/weizhiao/relink/blob/main/CONTRIBUTING.md

Examples of commit messages following the Conventional Commits specification. This helps maintain a readable project history.

```bash
fix(loader): reject malformed program header tables
```

```bash
refactor(elf): wrap ELF metadata with semantic types
```

```bash
docs(readme): clarify lazy binding workflow
```

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

### Typed symbol lookup (`LoadedCore::get`, `LoadedCore::get_version`)

Source: https://context7.com/weizhiao/relink/llms.txt

Provides type-safe lookup of symbols using `get::<T>()`, returning a `Symbol<T>` with a lifetime tied to the loaded image to prevent use-after-free errors.

```APIDOC
## `LoadedCore::get` / `LoadedCore::get_version` — Typed symbol lookup

`get::<T>` looks up a symbol by name and returns a `Symbol<T>` whose lifetime is tied to the loaded image, preventing use-after-free at compile time. `get_version` requires the `version` feature.

```rust
use elf_loader::{Loader, Result};

fn main() -> Result<()> {
    let lib = Loader::new()
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .relocate()?;

    // Function symbol
    let compute = unsafe {
        lib.get::<extern "C" fn(f64) -> f64>("compute")
            .expect("symbol 'compute' not found")
    };
    println!("compute(1.5) = {}", compute(1.5));

    // Static variable symbol
    let counter = unsafe {
        lib.get::<*mut i32>("global_counter")
            .expect("symbol 'global_counter' not found")
    };
    unsafe { **counter += 1; }

    // drop(lib);
    // compute(1.5); // compile error: `compute` cannot outlive `lib`
    Ok(())
}
```
```

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

### Load and Execute ELF Dynamic Library on Windows

Source: https://github.com/weizhiao/relink/blob/main/crates/windows-elf-loader/README.md

Demonstrates loading an ELF dynamic library, resolving symbols, and calling a function from it. Ensure ABI compatibility between the library and the host program.

```rust
use std::{collections::HashMap, ffi::CStr};
use windows_elf_loader::WinElfLoader;

fn main() {
    extern "sysv64" fn print(s: *const i8) {
        let s = unsafe { CStr::from_ptr(s).to_str().unwrap() };
        println!("{}", s);
    }
    // Symbols required by dynamic library liba.so
    let mut map = HashMap::new();
    map.insert("print", print as _);
    let pre_find = |name: &str| -> Option<*const ()> { map.get(name).copied() };
    let mut loader: WinElfLoader = WinElfLoader::new();
    // Load and relocate dynamic library liba.so
    let liba = loader
        .load_file(r".\crates\windows-elf-loader\example_dylib\liba.so")
        .unwrap()
        .relocator()
        .post_find_fn(&pre_find)
        .relocate()
        .unwrap();
    // Call function a in liba.so
    let f = unsafe { liba.get::<extern "sysv64" fn() -> i32>("a").unwrap() };
    println!("{}", f());
}
```

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

### Typed Symbol Lookup with LoadedCore::get

Source: https://context7.com/weizhiao/relink/llms.txt

Use `get::<T>` to look up a symbol by name and return a `Symbol<T>` with a lifetime tied to the loaded image, preventing use-after-free at compile time.

```rust
use elf_loader::{Loader, Result};

fn main() -> Result<()> {
    let lib = Loader::new()
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .relocate()?;

    // Function symbol
    let compute = unsafe {
        lib.get::<extern "C" fn(f64) -> f64>("compute")
            .expect("symbol 'compute' not found")
    };
    println!("compute(1.5) = {}", compute(1.5));

    // Static variable symbol
    let counter = unsafe {
        lib.get::<*mut i32>("global_counter")
            .expect("symbol 'global_counter' not found")
    };
    unsafe { **counter += 1; }

    // drop(lib);
    // compute(1.5); // compile error: `compute` cannot outlive `lib`
    Ok(())
}
```

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

### Run All Project Checks

Source: https://github.com/weizhiao/relink/blob/main/CONTRIBUTING.md

Formats all code and runs tests. These are the minimum checks to perform locally before submitting changes.

```bash
cargo fmt --all
cargo test
```

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

### Incremental Dependency Loading with Linker::load

Source: https://context7.com/weizhiao/relink/llms.txt

Demonstrates loading root modules and their dependencies into a shared context. Modules already committed to the context are reused without remapping. Ensure your `KeyResolver` implementation correctly handles loading root modules and resolving dependencies.

```rust
use elf_loader::{Result, input::ElfFile};
use elf_loader::linker::{
    DependencyRequest, KeyResolver, LinkContext, Linker,
    ResolvedKey,
};

struct SimpleResolver;

impl KeyResolver<'static, &'static str, ()> for SimpleResolver {
    fn load_root(&mut self, key: &&'static str) -> Result<ResolvedKey<'static, &'static str>> {
        Ok(ResolvedKey::load(*key, ElfFile::from_path(key)?))
    }

    fn resolve_dependency(
        &mut self,
        req: &DependencyRequest<'_, &'static str, ()>,
    ) -> Result<Option<ResolvedKey<'static, &'static str>>> {
        Ok(Some(ResolvedKey::load(
            req.needed(),   // use soname as key
            ElfFile::from_path(req.needed())?,
        )))
    }
}

fn main() -> Result<()> {
    let mut context = LinkContext::<&'static str, ()>::new();
    let mut linker = Linker::new().resolver(SimpleResolver);

    // First load: liba.so and its deps are mapped and committed
    let liba = linker.load(&mut context, "liba.so")?;
    println!("loaded {}", liba.name());

    // Second load: libb.so; if it DT_NEEDs liba.so, the committed copy is reused
    let libb = linker.load(&mut context, "libb.so")?;
    println!("loaded {}", libb.name());

    let f = unsafe { libb.get::<fn() -> i32>("b").unwrap() };
    println!("b() = {}", f());
    Ok(())
}
```

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

### Rust Type System Safety for Symbols

Source: https://github.com/weizhiao/relink/blob/main/README_zh.md

Typed symbols borrow the loaded image, ensuring they do not outlive the corresponding library. This example demonstrates how a symbol cannot outlive the library it was loaded from.

```rust
let symbol = unsafe {
    lib.get::<fn()>( "plugin_fn")
        .expect("symbol `plugin_fn` not found")
};
drop(lib);
// symbol(); // Cannot compile: symbol cannot outlive library
```

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

### Loader::load_mapped_dynamic

Source: https://context7.com/weizhiao/relink/llms.txt

`Loader::load_mapped_dynamic` wraps a kernel-mapped image for dynamic-linker startup scenarios. It accepts load bias, program headers, and entry address, performing no file I/O.

```APIDOC
## `Loader::load_mapped_dynamic` — Wrap a kernel-mapped image

For dynamic-linker startup scenarios where the kernel has already mapped the main executable before handing off to the interpreter. Accepts the load bias, program headers, and entry address. No file I/O is performed.

```rust
use elf_loader::{Loader, Result};
use elf_loader::elf::ElfPhdr;

fn main() -> Result<()> {
    // Typically provided by the kernel via AT_PHDR / AT_PHNUM / AT_ENTRY / AT_BASE
    let load_bias: usize = 0x7f0000000000;
    let entry: usize = 0x7f0000001234;
    let phdrs: Vec<ElfPhdr> = vec![/* ... */]; // from AT_PHDR

    let mut loader = Loader::new();
    let image = unsafe {
        loader.load_mapped_dynamic("main-exe", load_bias, phdrs, entry)?
    };

    println!(
        "{} mapped at [0x{:x}..0x{:x}]",
        image.name(),
        image.mapped_base(),
        image.mapped_base() + image.mapped_len()
    );
    Ok(())
}
```
```

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

### Loader::with_init / Loader::with_fini - Custom initialization and finalization handling

Source: https://context7.com/weizhiao/relink/llms.txt

Allows overriding the default handling of initialization (`.init`, `.init_array`) and finalization (`.fini`, `.fini_array`) functions. The `LifecycleContext` provides access to both single functions and arrays of functions.

```APIDOC
## `Loader::with_init` / `Loader::with_fini` / `LifecycleHandler` — Custom `.init` / `.fini` handling

Override how initialization (`.init`, `.init_array`) and finalization (`.fini`, `.fini_array`) functions are called. `LifecycleContext` exposes the single function and the array of functions separately.

```rust
use elf_loader::{Loader, Result, loader::LifecycleContext};

fn main() -> Result<()> {
    let mut loader = Loader::new()
        .with_init(|ctx: &LifecycleContext| {
            println!("init hook called");
            if let Some(f) = ctx.func() {
                println!("  single init fn at {:p}", f as *const ());
            }
            if let Some(arr) = ctx.func_array() {
                println!("  init_array: {} functions", arr.len());
                for f in arr {
                    unsafe { f() };
                }
            }
        })
        .with_fini(|ctx: &LifecycleContext| {
            println!("fini hook called");
            if let Some(f) = ctx.func() {
                unsafe { f() };
            }
        });

    let _lib = loader
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .relocate()?;
    Ok(())
}
```
```

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

### DylibWriter Usage

Source: https://github.com/weizhiao/relink/blob/main/tools/gen-elf/README.md

Demonstrates how to use DylibWriter to generate dynamic libraries with custom configurations, relocations, and symbols.

```APIDOC
## DylibWriter

Used for generating dynamic libraries. You can customize the generation using `ElfWriterConfig`.

### Method Signature
```rust
let arch = Arch::current();
let config = ElfWriterConfig::default()
    .with_base_addr(0x400000)
    .with_page_size(0x1000);
let writer = DylibWriter::with_config(arch, config);

let relocs = vec![
    RelocEntry::jump_slot("external_func", arch),
    RelocEntry::irelative(arch), // Test IFUNC
];

let symbols = vec![
    SymbolDesc::global_object("my_var", &[1, 2, 3, 4]),
    SymbolDesc::global_tls("my_tls", &[0xaa, 0xbb]),
    SymbolDesc::undefined_func("external_func"),
];

let output = writer.write(&relocs, &symbols)?;
println!("Generated ELF with {} relocations", output.relocations.len());
```

### Parameters
- `arch`: The target architecture.
- `config`: An `ElfWriterConfig` object for customization.
- `relocs`: A vector of `RelocEntry` defining relocation information.
- `symbols`: A vector of `SymbolDesc` defining symbols.
```

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

### Loader::new

Source: https://context7.com/weizhiao/relink/llms.txt

Creates a new loader instance with default configurations for mmap backend, lifecycle handlers, and relocation.

```APIDOC
## Loader::new — Create a default loader

`Loader::new()` returns a loader with the default mmap backend, C-ABI lifecycle handlers, no segment hook, no user data, and the native relocation backend.

### Usage Example
```rust
use elf_loader::{Loader, Result};

fn main() -> Result<()> {
    let mut loader = Loader::new();
    let lib = loader
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .relocate()?;

    let f = unsafe { lib.get::<fn() -> i32>("compute").unwrap() };
    println!("compute() = {}", f());
    Ok(())
}
```
```

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

### Run Tests with Full Features

Source: https://github.com/weizhiao/relink/blob/main/CONTRIBUTING.md

Runs tests with all feature flags enabled. Use this if your changes touch feature-gated code.

```bash
cargo test --features full
```

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

### Check Executable or PIE Files

Source: https://github.com/weizhiao/relink/blob/main/README_zh.md

Loads an executable or Position Independent Executable (PIE) file and prints its metadata such as name, entry point, and base address. This is useful for tools that need to inspect or manipulate executable files.

```rust
use elf_loader::{Loader, Result};

fn main() -> Result<()> {
    let mut loader = Loader::new();
    let exec = loader.load_exec("path/to/program")?;

    println!("name  = {}", exec.name());
    println!("entry = 0x{:x}", exec.entry());
    println!("base  = 0x{:x}", exec.base());

    Ok(())
}
```

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

### Custom `.init` / `.fini` Handling with `LifecycleHandler`

Source: https://context7.com/weizhiao/relink/llms.txt

Override initialization (`.init`, `.init_array`) and finalization (`.fini`, `.fini_array`) function calls using `with_init` and `with_fini`. The `LifecycleContext` provides access to single functions and arrays of functions.

```rust
use elf_loader::{Loader, Result, loader::LifecycleContext};

fn main() -> Result<()> {
    let mut loader = Loader::new()
        .with_init(|ctx: &LifecycleContext| {
            println!("init hook called");
            if let Some(f) = ctx.func() {
                println!("  single init fn at {:p}", f as *const ());
            }
            if let Some(arr) = ctx.func_array() {
                println!("  init_array: {} functions", arr.len());
                for f in arr {
                    unsafe { f() };
                }
            }
        })
        .with_fini(|ctx: &LifecycleContext| {
            println!("fini hook called");
            if let Some(f) = ctx.func() {
                unsafe { f() };
            }
        });

    let _lib = loader
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .relocate()?;
    Ok(())
}
```

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

### Lazy binding (`lazy`, `share_find_with_lazy`, `lazy_pre_find_fn`)

Source: https://context7.com/weizhiao/relink/llms.txt

Defers PLT slot fixups until the first call, improving startup performance. `share_find_with_lazy` reuses host lookup policies for initial relocation and PLT fixups.

```APIDOC
## `Relocator::lazy` / `share_find_with_lazy` — Lazy binding (PLT/GOT fixups)

Requires the `lazy-binding` feature. Defers PLT slot fixups to the first call. `share_find_with_lazy()` reuses the same host-lookup policy for both the initial relocation pass and PLT fixups. Use `lazy_pre_find_fn()` / `lazy_post_find_fn()` for separate lazy-fixup lookup rules.

```rust
// Cargo.toml: elf_loader = { version = "0.14", features = ["lazy-binding"] }
use elf_loader::{Loader, Result};

extern "C" fn host_double(x: i32) -> i32 { x * 2 }

fn main() -> Result<()> {
    let lib = Loader::new()
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .pre_find_fn(|name| {
            if name == "host_double" { Some(host_double as *const ()) } else { None }
        })
        .share_find_with_lazy()  // PLT fixups reuse the same pre_find policy
        .lazy()                  // enable lazy binding mode
        .relocate()?;

    let run = unsafe { lib.get::<extern "C" fn(i32) -> i32>("run").unwrap() };
    println!("run(21) = {}", run(21));  // PLT fixup happens on first call
    Ok(())
}
```
```

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

### Loader::for_arch

Source: https://context7.com/weizhiao/relink/llms.txt

Cross-architecture loading. Switches the relocation backend so that a loader on one ISA can load and inspect ELF objects targeting a different ISA. Must be called before with_dynamic_initializer. IFUNC resolvers, TLSDESC stubs, lazy-binding trampolines, and init arrays are not executed when SUPPORTS_NATIVE_RUNTIME == false.

```APIDOC
## `Loader::for_arch` — Cross-architecture loading

Switches the relocation backend so that a loader on one ISA can load and inspect ELF objects targeting a different ISA. Must be called before `with_dynamic_initializer`. IFUNC resolvers, TLSDESC stubs, lazy-binding trampolines, and init arrays are **not** executed when `SUPPORTS_NATIVE_RUNTIME == false`.

```rust
use elf_loader::{Loader, Result};
use elf_loader::arch::aarch64::relocation::AArch64Arch;

fn main() -> Result<()> {
    // Load an AArch64 .so on an x86_64 host (inspect, relocate, but don't run native code)
    let lib = Loader::new()
        .for_arch::<AArch64Arch>()
        .load_dylib("path/to/aarch64-plugin.so")?
        .relocator()
        .relocate()?;

    println!("name = {}, base = 0x{:x}", lib.name(), lib.base());
    Ok(())
}
```
```

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

### Loader::with_default_tls_resolver

Source: https://context7.com/weizhiao/relink/llms.txt

Enable TLS support. Modules that use Thread-Local Storage require a resolver. Call with_default_tls_resolver() to use the built-in resolver, or supply a custom one with with_tls_resolver::<MyTls>().

```APIDOC
## `Loader::with_default_tls_resolver` — Enable TLS support

Requires the `tls` feature (default). Modules that use Thread-Local Storage require a resolver. Call `with_default_tls_resolver()` to use the built-in resolver, or supply a custom one with `with_tls_resolver::<MyTls>()`.

```rust
// Cargo.toml: elf_loader = { version = "0.14", features = ["tls"] }  (default)
use elf_loader::{Loader, Result};

fn main() -> Result<()> {
    let lib = Loader::new()
        .with_default_tls_resolver()
        .load_dylib("path/to/tls-plugin.so")?
        .relocator()
        .relocate()?;

    println!("tls_mod_id = {:?}", lib.tls_mod_id());
    Ok(())
}
```
```

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

### Load Dylib with Host Function Binding

Source: https://context7.com/weizhiao/relink/llms.txt

Load a shared object and provide a host function to be resolved by the dylib. This is useful for enabling communication between the host and the loaded plugin. The dylib must be relocated before use.

```rust
use elf_loader::{Loader, Result};

extern "C" fn host_double(value: i32) -> i32 {
    value * 2
}

fn main() -> Result<()> {
    let mut loader = Loader::new();

    // From a file path
    let lib = loader
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .pre_find_fn(|name| {
            if name == "host_double" {
                Some(host_double as *const ()) 
            } else {
                None
            }
        })
        .relocate()?;

    let run = unsafe {
        lib.get::<extern "C" fn(i32) -> i32>("run")
            .expect("symbol `run` not found")
    };
    assert_eq!(run(21), 42);
    Ok(())
}
```

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

### Scan-First Dependency Graph Loading

Source: https://context7.com/weizhiao/relink/llms.txt

Implement a custom dependency loading strategy using `Linker`, `KeyResolver`, and `LinkContext`. This approach discovers the full `DT_NEEDED` graph before mapping any memory, allowing for custom pipeline passes to modify the layout and materialization before atomic mapping and relocation.

```rust
use elf_loader::{Result, input::ElfFile};
use elf_loader::linker::{
    DependencyRequest, KeyResolver, LinkContext, LinkPass, LinkPassPlan,
    Linker, Materialization, ReorderPass,
    ResolvedKey,
};

struct MyResolver {
    paths: std::collections::HashMap<&'static str, String>,
}

impl KeyResolver<'static, &'static str, ()> for MyResolver {
    fn load_root(&mut self, key: &&'static str) -> Result<ResolvedKey<'static, &'static str>> {
        let path = self.paths.get(*key).expect("unknown key");
        Ok(ResolvedKey::load(*key, ElfFile::from_path(path)?))
    }

    fn resolve_dependency(
        &mut self,
        req: &DependencyRequest<'_, &'static str, ()>,
    ) -> Result<Option<ResolvedKey<'static, &'static str>>> {
        // Map DT_NEEDED sonames to canonical keys
        let resolved = match req.needed() {
            "liba.so" => ResolvedKey::load("liba", ElfFile::from_path(self.paths["liba"].as_str())?),
            _ => return Ok(None),
        };
        Ok(Some(resolved))
    }
}

// Layout pass: request section-region materialization for the root module
struct SectionRegionRoot;
impl LinkPass<&'static str, ReorderPass> for SectionRegionRoot {
    fn run(&mut self, plan: &mut LinkPassPlan<'_, &'static str, ReorderPass>) -> Result<()> {
        plan.set_materialization(plan.root(), Materialization::SectionRegions);
        Ok(())
    }
}

fn main() -> Result<()> {
    fn print(s: &str) { println!("{}", s); }
    let pre_find = |name: &str| -> Option<*const ()> {
        if name == "print" { Some(print as _) } else { None }
    };

    let mut paths = std::collections::HashMap::new();
    paths.insert("libc", "path/to/libc.so".to_string());
    paths.insert("liba", "path/to/liba.so".to_string());

    let mut context = LinkContext::<&'static str, ()>::new();

    let loaded = Linker::new()
        .resolver(MyResolver { paths })
        .map_pipeline(|mut pipeline| {
            pipeline.push(SectionRegionRoot);
            pipeline
        })
        .map_relocator(|relocator| relocator.pre_find_fn(pre_find))
        .load_scan_first(&mut context, "libc")?;

    let c = unsafe { loaded.get::<fn() -> i32>("c").unwrap() };
    println!("c() = {}", c());
    Ok(())
}
```

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

### File-Backed ELF Input

Source: https://context7.com/weizhiao/relink/llms.txt

Use `ElfFile::from_path` to open an ELF file without reading its entire content into memory. This is efficient for large ELF objects as the loader streams data as needed.

```rust
use elf_loader::{Loader, Result, input::ElfFile};

fn main() -> Result<()> {
    let file = ElfFile::from_path("path/to/plugin.so")?;
    let lib = Loader::new()
        .load_dylib(file)?
        .relocator()
        .relocate()?;
    println!("loaded {}", lib.name());
    Ok(())
}
```

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

### Attach Custom Metadata with `Loader::with_dynamic_initializer`

Source: https://context7.com/weizhiao/relink/llms.txt

Use this to attach custom metadata to dynamic images at load time. The initializer closure receives the `RawDynamic` image to read its properties before setting user data. Retrieve the data later using `lib.user_data()`.

```rust
use elf_loader::{Loader, Result};
use std::time::SystemTime;

#[derive(Debug, Default)]
struct MyMeta {
    load_time: Option<SystemTime>,
    id: u32,
}

fn main() -> Result<()> {
    let mut loader = Loader::new()
        .with_dynamic_initializer::<MyMeta>(|image| {
            println!("initializing user data for '{}'", image.name());
            if let Some(meta) = image.user_data_mut() {
                meta.load_time = Some(SystemTime::now());
                meta.id = 42;
            }
            Ok(())
        });

    let lib = loader
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .relocate()?;

    println!("metadata: {:?}", lib.user_data());
    Ok(())
}
```

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

### Load Dynamic Library from Bytes

Source: https://context7.com/weizhiao/relink/llms.txt

Load a dynamic library directly from a byte buffer (`&[u8]`, `&Vec<u8>`, or `ElfBinary`). Use `ElfBinary::new` to provide a name for anonymous byte buffers.

```rust
use elf_loader::{Loader, Result, input::ElfBinary};

fn main() -> Result<()> {
    let bytes = std::fs::read("path/to/plugin.so").unwrap();

    // Named in-memory buffer
    let lib = Loader::new()
        .load_dylib(ElfBinary::new("plugin.so", &bytes))?
        .relocator()
        .relocate()?;

    println!("loaded {} at 0x{:x}", lib.name(), lib.base());

    // Anonymous byte slice (name becomes "<memory>")
    let lib2 = Loader::new()
        .load_dylib(&bytes)?
        .relocator()
        .relocate()?;

    println!("loaded {} at 0x{:x}", lib2.name(), lib2.base());
    Ok(())
}
```

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

### Load an Executable or PIE Image

Source: https://context7.com/weizhiao/relink/llms.txt

Load an executable or a Position-Independent Executable (PIE) image. This method returns metadata about the loaded executable, such as its entry point and base address. Dynamic executables can be relocated.

```rust
use elf_loader::{Loader, Result};

fn main() -> Result<()> {
    let mut loader = Loader::new();
    let exec = loader.load_exec("path/to/program")?;

    println!("name  = {}", exec.name());
    println!("entry = 0x{:x}", exec.entry());
    println!("base  = 0x{:x}", exec.base());
    Ok(())
}
```

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

### Optimize Runtime Dependency Graph with Linker

Source: https://github.com/weizhiao/relink/blob/main/README.md

Uses the scan-first linker to resolve dependencies, build a plan, and optimize layout before mapping and relocating modules. This allows for mutation of layout and materialization.

```rust
use elf_loader::{Result, input::ElfFile};
use elf_loader::linker::{
    DependencyRequest,
    KeyResolver,
    LinkContext,
    LinkPassPlan,
    Linker,
    Materialization,
    ReorderPass,
    ResolvedKey,
};

struct Resolver;

impl KeyResolver<'static, &'static str, ()> for Resolver {
    fn load_root(&mut self, key: &&'static str) -> Result<ResolvedKey<'static, &'static str>> {
        Ok(ResolvedKey::load(*key, ElfFile::from_path("path/to/plugin.so")?))
    }

    fn resolve_dependency(
        &mut self,
        _req: &DependencyRequest<'_, &'static str, ()>,
    ) -> Result<Option<ResolvedKey<'static, &'static str>>> {
        Ok(None)
    }
}

fn main() -> Result<()> {
    let mut context = LinkContext::<&'static str, ()>::new();
    let resolver = Resolver;

    let configure = |plan: &mut LinkPassPlan<'_, &'static str, ReorderPass>| -> Result<()> {
        plan.set_materialization(plan.root(), Materialization::SectionRegions);
        Ok(())
    };

    let plugin = Linker::new()
        .resolver(resolver)
        .map_pipeline(|mut pipeline| {
            pipeline.push(configure);
            pipeline
        })
        .load_scan_first(&mut context, "plugin")?;

    let _ = plugin;
    Ok(())
}
```

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

### Loader::load_dylib - Load from in-memory bytes

Source: https://context7.com/weizhiao/relink/llms.txt

Loads a dynamic library from a byte buffer. Supports named buffers using `ElfBinary` or anonymous byte slices.

```APIDOC
## `Loader::load_dylib` with in-memory bytes — Load from a byte buffer

Any `&[u8]`, `&Vec<u8>`, or `ElfBinary` can be passed directly. Use `ElfBinary::new` to attach a human-readable name to an anonymous byte buffer.

```rust
use elf_loader::{Loader, Result, input::ElfBinary};

fn main() -> Result<()> {
    let bytes = std::fs::read("path/to/plugin.so").unwrap();

    // Named in-memory buffer
    let lib = Loader::new()
        .load_dylib(ElfBinary::new("plugin.so", &bytes))
        .relocator()
        .relocate()?;

    println!("loaded {} at 0x{:x}", lib.name(), lib.base());

    // Anonymous byte slice (name becomes "<memory>")
    let lib2 = Loader::new()
        .load_dylib(&bytes)?
        .relocator()
        .relocate()?;

    println!("loaded {} at 0x{:x}", lib2.name(), lib2.base());
    Ok(())
}
```
```

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

### Observe Segment Loading with `Loader::with_hook`

Source: https://context7.com/weizhiao/relink/llms.txt

Attach a callback using `with_hook` to observe each program header being mapped. The hook receives `LoadHookContext` and can inspect segment details. Returning an error aborts the load.

```rust
use elf_loader::{Loader, Result, loader::LoadHookContext};

fn main() -> Result<()> {
    let mut loader = Loader::new().with_hook(|ctx: &LoadHookContext| {
        println!(
            "[{}] segment type={:?} offset=0x{:x} vaddr=0x{:x} filesz=0x{:x} memsz=0x{:x}",
            ctx.name(),
            ctx.phdr().program_type(),
            ctx.phdr().p_offset(),
            ctx.phdr().p_vaddr(),
            ctx.phdr().p_filesz(),
            ctx.phdr().p_memsz(),
        );
        Ok(())
    });

    let _lib = loader
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .relocate()?;
    Ok(())
}
```

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

### Cross-Architecture Loading with `Loader::for_arch`

Source: https://context7.com/weizhiao/relink/llms.txt

Load and inspect ELF objects for a different ISA than the host. This must be called before `with_dynamic_initializer`. Note that IFUNC resolvers, TLSDESC stubs, and other runtime features are not executed when `SUPPORTS_NATIVE_RUNTIME == false`.

```rust
use elf_loader::{Loader, Result};
use elf_loader::arch::aarch64::relocation::AArch64Arch;

fn main() -> Result<()> {
    // Load an AArch64 .so on an x86_64 host (inspect, relocate, but don't run native code)
    let lib = Loader::new()
        .for_arch::<AArch64Arch>()
        .load_dylib("path/to/aarch64-plugin.so")?
        .relocator()
        .relocate()?;

    println!("name = {}, base = 0x{:x}", lib.name(), lib.base());
    Ok(())
}
```

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

### Loader::with_dynamic_initializer

Source: https://context7.com/weizhiao/relink/llms.txt

Attach custom metadata to every dynamic image at load time. The initializer closure receives the RawDynamic image so it can read name(), dependencies, and mapping addresses before setting user_data_mut(). After relocation, call lib.user_data() to retrieve it.

```APIDOC
## `Loader::with_dynamic_initializer` — Per-image user data

Attach custom metadata to every dynamic image at load time. The initializer closure receives the `RawDynamic` image so it can read `name()`, dependencies, and mapping addresses before setting `user_data_mut()`. After relocation, call `lib.user_data()` to retrieve it.

```rust
use elf_loader::{Loader, Result};
use std::time::SystemTime;

#[derive(Debug, Default)]
struct MyMeta {
    load_time: Option<SystemTime>,
    id: u32,
}

fn main() -> Result<()> {
    let mut loader = Loader::new()
        .with_dynamic_initializer::<MyMeta>(|image| {
            println!("initializing user data for '{}'", image.name());
            if let Some(meta) = image.user_data_mut() {
                meta.load_time = Some(SystemTime::now());
                meta.id = 42;
            }
            Ok(())
        });

    let lib = loader
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .relocate()?;

    println!("metadata: {:?}", lib.user_data());
    Ok(())
}
```
```

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

### Generate Dynamic Library with gen-elf

Source: https://github.com/weizhiao/relink/blob/main/tools/gen-elf/README.md

Use DylibWriter to create shared objects (.so) with custom configurations, relocations, and symbols. Configure base address and page size for memory mapping tests.

```rust
use gen_elf::{Arch, DylibWriter, ElfWriterConfig, RelocEntry, SymbolDesc};

let arch = Arch::current();
let config = ElfWriterConfig::default()
    .with_base_addr(0x400000)
    .with_page_size(0x1000);
let writer = DylibWriter::with_config(arch, config);

let relocs = vec![
    RelocEntry::jump_slot("external_func", arch),
    RelocEntry::irelative(arch), // Test IFUNC
];

let symbols = vec![
    SymbolDesc::global_object("my_var", &[1, 2, 3, 4]),
    SymbolDesc::global_tls("my_tls", &[0xaa, 0xbb]),
    SymbolDesc::undefined_func("external_func"),
];

let output = writer.write(&relocs, &symbols)?;
println!("Generated ELF with {} relocations", output.relocations.len());
```

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

### ObjectWriter Usage

Source: https://github.com/weizhiao/relink/blob/main/tools/gen-elf/README.md

Illustrates how to use ObjectWriter to generate relocatable object files.

```APIDOC
## ObjectWriter

Used for generating relocatable object files.

### Method Signature
```rust
let arch = Arch::X86_64;
let writer = ObjectWriter::new(arch);

let symbols = vec![
    SymbolDesc::global_func("my_func", &[0x90, 0xc3]), // nop; ret
    SymbolDesc::global_object("data_var", &[0x01, 0x02]),
];

// Symbols and Relocs
writer.write_file("test.o", &symbols, &[])?;
```

### Parameters
- `arch`: The target architecture.
- `symbols`: A vector of `SymbolDesc` defining symbols.
- `relocs`: A vector of `RelocEntry` defining relocation information (empty in this example).
- `filename`: The name of the output file (e.g., "test.o").
```

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

### Enable TLS Support with `Loader::with_default_tls_resolver`

Source: https://context7.com/weizhiao/relink/llms.txt

Modules using Thread-Local Storage require a resolver. Call `with_default_tls_resolver()` for the built-in resolver, or provide a custom one with `with_tls_resolver::<MyTls>()`. Ensure the `tls` feature is enabled in Cargo.toml.

```rust
// Cargo.toml: elf_loader = { version = "0.14", features = ["tls"] }  (default)
use elf_loader::{Loader, Result};

fn main() -> Result<()> {
    let lib = Loader::new()
        .with_default_tls_resolver()
        .load_dylib("path/to/tls-plugin.so")?
        .relocator()
        .relocate()?;

    println!("tls_mod_id = {:?}", lib.tls_mod_id());
    Ok(())
}
```

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

### Loader::load_dylib

Source: https://context7.com/weizhiao/relink/llms.txt

Loads a shared object (ET_DYN) from various input types, returning a RawDylib that needs relocation.

```APIDOC
## Loader::load_dylib — Load a shared object (`ET_DYN`)

Reads, maps, and validates a `PT_DYNAMIC` shared object from any `IntoElfReader` input (path, `&[u8]`, `ElfFile`, `ElfBinary`). Returns a `RawDylib` that must be relocated before use. Rejects `ET_EXEC` inputs.

### Usage Example
```rust
use elf_loader::{Loader, Result};

extern "C" fn host_double(value: i32) -> i32 {
    value * 2
}

fn main() -> Result<()> {
    let mut loader = Loader::new();

    // From a file path
    let lib = loader
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .pre_find_fn(|name| {
            if name == "host_double" {
                Some(host_double as *const ())
            } else {
                None
            }
        })
        .relocate()?;

    let run = unsafe {
        lib.get::<extern "C" fn(i32) -> i32>("run")
            .expect("symbol `run` not found")
    };
    assert_eq!(run(21), 42);
    Ok(())
}
```
```

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

### Implement Custom Symbol Lookup with HostSymbols

Source: https://context7.com/weizhiao/relink/llms.txt

Use `pre_find` with a type implementing `SymbolLookup` to check host symbols before scanning the relocation scope. Return `None` to fall through.

```rust
use elf_loader::{Loader, Result};
use elf_loader::relocation::SymbolLookup;
use std::collections::HashMap;

struct HostSymbols {
    map: HashMap<String, *const ()>,
}

impl SymbolLookup for HostSymbols {
    fn lookup(&self, name: &str) -> Option<*const ()> {
        self.map.get(name).copied()
    }
}

fn main() -> Result<()> {
    extern "C" fn host_add(a: i32, b: i32) -> i32 { a + b }

    let mut host = HostSymbols { map: HashMap::new() };
    host.map.insert("host_add".to_string(), host_add as _);

    let lib = Loader::new()
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .pre_find(&host)   // check host symbols first
        .relocate()?;

    let run = unsafe { lib.get::<fn(i32, i32) -> i32>("run").unwrap() };
    println!("run(3, 4) = {}", run(3, 4));
    Ok(())
}
```

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

### Optimize Runtime Dependencies with Linker

Source: https://github.com/weizhiao/relink/blob/main/README_zh.md

Uses the `Linker` to optimize the runtime dependency graph before mapping modules. The `scan-first` path resolves `DT_NEEDED` edges to build a plan, allowing modification of layout and materialization strategies before actual mapping and relocation.

```rust
use elf_loader::{Result, input::ElfFile};
use elf_loader::linker::
    DependencyRequest, KeyResolver, LinkContext, LinkPassPlan, Linker,
    Materialization,
    ReorderPass, ResolvedKey,
;

struct Resolver;

impl KeyResolver<'static, &'static str, ()> for Resolver {
    fn load_root(&mut self, key: &&'static str) -> Result<ResolvedKey<'static, &'static str>> {
        Ok(ResolvedKey::load(*key, ElfFile::from_path("path/to/plugin.so")?))
    }

    fn resolve_dependency(
        &mut self,
        _req: &DependencyRequest<'_, &'static str, ()>,
    ) -> Result<Option<ResolvedKey<'static, &'static str>>> {
        Ok(None)
    }
}

fn main() -> Result<()> {
    let mut context = LinkContext::<&'static str, ()>::new();
    let resolver = Resolver;

    let configure = |plan: &mut LinkPassPlan<'_, &'static str, (), ReorderPass>| -> Result<()> {
        plan.set_materialization(plan.root(), Materialization::SectionRegions);
        Ok(())
    };

    let plugin = Linker::new()
        .resolver(resolver)
        .map_pipeline(|mut pipeline| {
            pipeline.push(configure);
            pipeline
        })
        .load_scan_first(&mut context, "plugin")?;

    let _ = plugin;
    Ok(())
}
```

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

### Loader::load

Source: https://context7.com/weizhiao/relink/llms.txt

Auto-detects the ELF type (dylib, executable, or relocatable object) and loads it accordingly.

```APIDOC
## Loader::load — Auto-detect ELF type and load

Inspects the ELF header and program headers to decide whether the input is a dylib, executable, or relocatable object, then dispatches to the correct load path. Use this when the caller does not know in advance what kind of ELF is being loaded.

### Usage Example
```rust
use elf_loader::{Loader, Result, image::RawElf};

fn main() -> Result<()> {
    let mut loader = Loader::new();
    match loader.load("path/to/unknown.elf")? {
        RawElf::Dylib(raw) => {
            let lib = raw.relocator().relocate()?;
            println!("loaded dylib: {}", lib.name());
        }
        RawElf::Exec(raw) => {
            println!("loaded exec: {}", raw.name());
        }
        RawElf::Object(raw) => {
            let obj = raw.relocator().relocate()?;
            println!("loaded object: {}", obj.name());
        }
    }
    Ok(())
}
```
```

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

### Loader::with_hook - Observe segment loading

Source: https://context7.com/weizhiao/relink/llms.txt

Attaches a callback (`LoadHook`) that is invoked for each program header being mapped. The hook receives context about the segment, allowing inspection of its properties. Returning an error from the hook aborts the loading process.

```APIDOC
## `Loader::with_hook` / `LoadHook` — Observe segment loading

Attach a callback that receives a `LoadHookContext` for every program header being mapped. The hook may inspect segment type, offsets, sizes, and flags. Returning an error aborts the load.

```rust
use elf_loader::{Loader, Result, loader::LoadHookContext};

fn main() -> Result<()> {
    let mut loader = Loader::new().with_hook(|ctx: &LoadHookContext| {
        println!(
            "[{}] segment type={:?} offset=0x{:x} vaddr=0x{:x} filesz=0x{:x} memsz=0x{:x}",
            ctx.name(),
            ctx.phdr().program_type(),
            ctx.phdr().p_offset(),
            ctx.phdr().p_vaddr(),
            ctx.phdr().p_filesz(),
            ctx.phdr().p_memsz(),
        );
        Ok(())
    });

    let _lib = loader
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .relocate()?;
    Ok(())
}
```
```

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

### Loader::load_exec

Source: https://context7.com/weizhiao/relink/llms.txt

Loads an executable or PIE image (ET_EXEC or ET_DYN with PT_INTERP), providing metadata like entry point and load base.

```APIDOC
## Loader::load_exec — Load an executable or PIE image

Accepts both static executables and dynamically-linked / PIE-style images (`ET_EXEC` or `ET_DYN` with `PT_INTERP`). Returns metadata such as entry point and load base. Dynamic executables can be relocated.

### Usage Example
```rust
use elf_loader::{Loader, Result};

fn main() -> Result<()> {
    let mut loader = Loader::new();
    let exec = loader.load_exec("path/to/program")?;

    println!("name  = {}", exec.name());
    println!("entry = 0x{:x}", exec.entry());
    println!("base  = 0x{:x}", exec.base());
    Ok(())
}
```
```

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

### Load Mixed .o and .so Files

Source: https://github.com/weizhiao/relink/blob/main/README_zh.md

Loads both relocatable object files (.o) and shared libraries (.so) into the same loader context. This requires enabling the `object` feature. It allows for complex linking scenarios where different types of ELF files need to be combined.

```rust
use elf_loader::{Loader, Result};

fn main() -> Result<()> {
    let mut loader = Loader::new();

    let base = loader
        .load_object("path/to/base.o")?
        .relocator()
        .pre_find_fn(|_| None)
        .relocate()?;

    let plugin = loader
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .scope([&base])
        .relocate()?;

    let _ = plugin;
    Ok(())
}
```

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

### Add Relink Crate with Default Features

Source: https://github.com/weizhiao/relink/blob/main/README.md

Instructions for adding the `elf_loader` crate to your Rust project's dependencies using the default feature set.

```toml
[dependencies]
elf_loader = "0.14"
```
Tokens:
Raw