Crate elf_loader 

Relink

Relink is a high-performance, no_std-friendly ELF loader and runtime linker for Rust. It maps ELF images from files or memory, performs relocations at runtime, and exposes typed symbol lookups with Rust lifetimes.

Start with Loader

• Use Loader::load to auto-detect whether the input is a dylib, executable, or relocatable object.
• Use Loader::scan to classify executable or dynamic ELF metadata without mapping it.
• Use Loader::load_dylib or Loader::load_exec when you want strict type checks.
• Use Loader::load_dynamic when you want any PT_DYNAMIC image, including a dynamic ET_EXEC.
• Use Loader::scan and Loader::load_scanned_dynamic to split dynamic metadata discovery from mapping.
• Use Loader::load_object to load ET_REL object files when the object feature is enabled.
• Inputs can come from file paths, input::Path / input::PathBuf, raw bytes, input::ElfFile, or input::ElfBinary.

Highlights

• Safer symbol lifetimes. Typed symbols borrow the loaded image, so they cannot outlive the library that produced them.
• Hybrid linking. Compose .so, .o, and synthetic modules at runtime with scope() and extend_scope().
• Explicit dependency loading. Build your own dependency policy with an actual Loader, linker::KeyResolver, linker::Linker, and linker::LinkContext.
• Deep customization. Inject host or bridge symbols with image::SyntheticModule, intercept relocations with handlers, and inspect segments with loader::LoadHook.
• Optional advanced features. TLS relocation handling, lazy binding, relocatable object loading, logging, and versioned symbol lookup are feature-gated.

Example

use elf_loader::{
    Loader, Result,
    image::{SyntheticSymbol, SyntheticModule},
};

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

fn main() -> Result<()> {
    let host = SyntheticModule::new(
        "__host",
        [SyntheticSymbol::function("host_double", host_double as *const ())],
    );

    let lib = Loader::new()
        .load_dylib("path/to/plugin.so")?
        .relocator()
        .scope([host])
        .relocate()?;

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

Loading Dependencies With linker::Linker

Use linker::Linker::load when you want a reusable linker::LinkContext and resolver-driven DT_NEEDED dependency loading. The built-in linker::SearchPathResolver covers the common filesystem search-path case; implement linker::KeyResolver when dependencies come from memory, package stores, or another registry.

use elf_loader::{
    Result,
    input::PathBuf,
    linker::{LinkContext, Linker, SearchPathResolver},
};

fn main() -> Result<()> {
    let root = PathBuf::from("path/to/plugin.so");
    let mut context: LinkContext<PathBuf, ()> = LinkContext::new();

    let loaded = Linker::new()
        .resolver(SearchPathResolver::new())
        .load(&mut context, root)?;

    let run = unsafe {
        loaded
            .get::<extern "C" fn() -> i32>("run")
            .expect("symbol `run` not found")
    };
    let _ = run();

    Ok(())
}

Feature Flags

• tls (default): enables TLS relocation handling. For TLS-using modules, start from Loader::with_default_tls_resolver or provide a custom TLS resolver.
• lazy-binding: enables Relocator::lazy and PLT/GOT lazy binding.
• object: enables Loader::load_object and relocatable object (ET_REL) loading.
• version: enables version-aware symbol lookup via ElfCore::get_version.
• log, portable-atomic, and use-syscall: optional integrations for diagnostics and specialized targets.

More

• The examples directory covers loading from memory, Linker::load, scan-first linking, lifecycle hooks, relocation handlers, and object loading.
• The crate currently targets x86_64, x86, aarch64, arm, riscv64, riscv32, and loongarch64.
• Relocatable object support is currently centered on x86_64.

Re-exports

pub use loader::Loader;

Modules

arch

Architecture-specific definitions and relocation logic.

elf

ELF (Executable and Linkable Format) parsing and data structures.

image

Public image types returned by the loader and relocation pipeline.

input

ELF input traits and built-in data sources.

linker

Explicit linking and dependency-resolution primitives.

loader

Loading entry points and customization hooks.

os

Operating system and environment abstractions.

relocation

Relocation configuration, symbol scopes, and binding policy.

tls

Thread Local Storage (TLS) management.

Structs

RelocationFailure

Detailed relocation failure carried separately so the top-level Error stays compact.

Enums

CustomError

Structured user-defined error details.

Error

Error types used throughout the elf_loader library. These errors represent various failure conditions that can occur during ELF file loading, parsing, and relocation operations.

IoError

Structured I/O error details.

LinkerError

Structured linker error details.

MmapError

Structured memory-mapping error details.

ParseDynamicError

Structured dynamic-section parsing error details.

ParseEhdrError

Structured ELF header parsing error details.

ParsePhdrError

Structured program-header parsing error details.

RelocationError

Structured relocation error details.

TlsError

Structured TLS error details.

Traits

ByteRepr

Types that can be safely viewed from arbitrary bytes.

Type Aliases

Result

A type alias for Results returned by elf_loader functions.