dlopen-rs

English | 中文

[Documentation]

dlopen-rs is a dynamic linker fully implemented in Rust, providing a set of Rust-friendly interfaces for manipulating dynamic libraries, as well as C-compatible interfaces consistent with libc behavior.

Usage

You can use dlopen-rs as a replacement for libloading to load dynamic libraries. It also allows replacing libc's dlopen, dlsym, dl_iterate_phdr and other functions with implementations from dlopen-rs using LD_PRELOAD without code modifications.

# Compile the library as a dynamic library
$ cargo build -r -p cdylib
# Compile test cases
$ cargo build -r -p dlopen-rs --example preload
# Replace libc implementations with ours
$ RUST_LOG=trace LD_PRELOAD=./target/release/libdlopen.so ./target/release/examples/preload

Advantages

1. Provides support for loading ELF dynamic libraries to #![no_std] targets.
2. Enables easy runtime replacement of symbols in shared libraries with custom implementations.
3. Typically faster than ld.so for dynamic library loading and symbol resolution.
4. Offers Rust-friendly interfaces with ergonomic design.
5. Allows repeated loading of the same dynamic library into memory. Using the CUSTOM_NOT_REGISTER flag in OpenFlags enables multiple coexisting copies of a library (identical or modified) in memory, facilitating runtime dynamic library hot-swapping.

Feature

Architecture Support

Examples

Example 1

The dlopen interface is used to load dynamic libraries, and the dl_iterate_phdr interface is used to iterate through the already loaded dynamic libraries. Additionally, this library uses the log crate, and you can use your preferred library to output log information to view the workflow of dlopen-rs. In the examples of this library, the env_logger crate is used.

use dlopen_rs::ELFLibrary;
use std::path::Path;

fn main() {
    std::env::set_var("RUST_LOG", "trace");
    env_logger::init();
    dlopen_rs::init();
    let path = Path::new("./target/release/libexample.so");
    let libexample =
        ElfLibrary::dlopen(path, OpenFlags::RTLD_LOCAL | OpenFlags::RTLD_LAZY).unwrap();
    let add = unsafe { libexample.get::<fn(i32, i32) -> i32>("add").unwrap() };
    println!("{}", add(1, 1));

    let print = unsafe { libexample.get::<fn(&str)>("print").unwrap() };
    print("dlopen-rs: hello world");
	
	let dl_info = ElfLibrary::dladdr(print.into_raw() as usize).unwrap();
    println!("{:?}", dl_info);

    ElfLibrary::dl_iterate_phdr(|info| {
        println!(
            "iterate dynamic library: {}",
            unsafe { CStr::from_ptr(info.dlpi_name).to_str().unwrap() }
        );
        Ok(())
    })
    .unwrap();
}

Example 2

Fine-grained control of the load flow of the dynamic library, you can replace certain functions in the dynamic library that need to be relocated with your own implementation. In the following example, we replace malloc with mymalloc in the dynamic library and turn on lazy binding.

use dlopen_rs::ELFLibrary;
use libc::size_t;
use std::{ffi::c_void, path::Path};

extern "C" fn mymalloc(size: size_t) -> *mut c_void {
    println!("malloc:{}bytes", size);
    unsafe { libc::malloc(size) }
}

fn main() {
    std::env::set_var("RUST_LOG", "debug");
    env_logger::init();
    dlopen_rs::init();
    let path = Path::new("./target/release/libexample.so");
    let libc = ElfLibrary::load_existing("libc.so.6").unwrap();
    let libgcc = ElfLibrary::load_existing("libgcc_s.so.1").unwrap();

    let libexample = ElfLibrary::from_file(path, OpenFlags::CUSTOM_NOT_REGISTER)
        .unwrap()
        .relocate_with(&[libc, libgcc], &|name: &str| {
            if name == "malloc" {
                return Some(mymalloc as _);
            } else {
                return None;
            }
        })
        .unwrap();

    let add = unsafe { libexample.get::<fn(i32, i32) -> i32>("add").unwrap() };
    println!("{}", add(1, 1));

    let print = unsafe { libexample.get::<fn(&str)>("print").unwrap() };
    print("dlopen-rs: hello world");
}

Minimum Supported Rust Version

Rust 1.85 or higher.

TODO

• dlinfo have not been implemented yet. dlerror currently only returns NULL.
• RTLD_NEXT for dlsym has not been implemented.
• When dlopen fails, the newly loaded dynamic library is destroyed, but the functions in .fini are not called.

Supplement

If you encounter any issues during use, feel free to raise them on GitHub. We warmly welcome everyone to contribute code to help improve the functionality of dlopen-rs. 😊