Struct Library 

pub struct Library { /* private fields */ }

A loaded dynamic library.

The library is unloaded when this value is dropped (or explicitly with close). Symbols borrowed from it cannot outlive it.

Libraries that cannot be unloaded

Borrowing stops your code from using a library after it is unloaded, but some libraries leave things behind that keep running their code: threads they started, thread-local destructors, atexit handlers, or callbacks registered elsewhere. Unloading those crashes later, far from the cause (libclang on Windows is one). Keep such libraries loaded for the life of the process with leak, a static, or OpenOptions::no_delete.

Implementations

impl Library

pub unsafe fn open(path: impl AsRef<OsStr>) -> Result<Self>

Loads the library at path, or searches for it by name using the platform’s rules when path contains no directory separator.

On Unix this is dlopen(path, RTLD_NOW | RTLD_LOCAL); use os::unix::OpenOptions for other flags. On Windows this is LoadLibraryExW(path, NULL, 0), with the system’s error dialogs suppressed.

Safety

Loading a library runs its initialisers (and, on Windows, DllMain), which may do anything. The caller must trust the library.

Examples found in repository

examples/symbols.rs (line 30)

fn main() -> dlsym::Result<()> {
    // SAFETY: the C math library's initialisers are trusted.
    let libm = unsafe { Library::open(LIBM) }?;

    // SAFETY: `cos` has this signature.
    let cos = unsafe { libm.get::<unsafe extern "C" fn(f64) -> f64>(c"cos") }?;
    // SAFETY: `cos` is defined for every `f64`.
    println!("cos(0) = {}", unsafe { cos.call((0.0,)) });

    // Variadic functions are called through `with`; the raw function
    // pointer cannot escape the closure without `unsafe`.
    #[cfg(not(windows))]
    let libc = Library::this()?;
    // SAFETY: msvcrt is a system library.
    #[cfg(windows)]
    let libc = unsafe { Library::open("msvcrt.dll") }?;
    // SAFETY: `sprintf` has this signature.
    let sprintf = unsafe {
        libc.get::<unsafe extern "C" fn(*mut c_char, *const c_char, ...) -> c_int>(c"sprintf")
    }?;
    let mut buf = [0 as c_char; 64];
    // SAFETY: the buffer is large enough and the format matches.
    unsafe {
        sprintf.with(|f| {
            f(
                buf.as_mut_ptr(),
                c"%s has %d symbols".as_ptr(),
                c"this example".as_ptr(),
                2,
            )
        })
    };
    // SAFETY: `sprintf` NUL-terminated the buffer.
    let text = unsafe { CStr::from_ptr(buf.as_ptr()) };
    println!("{}", text.to_string_lossy());

    // `cos` borrows `libm`: uncommenting this line makes the call below a
    // compile error instead of a use-after-unload.
    // drop(libm);
    // SAFETY: as above.
    println!("cos(pi) = {}", unsafe { cos.call((std::f64::consts::PI,)) });
    Ok(())
}

pub unsafe fn open_first<I>(candidates: I) -> Result<Self>

where I: IntoIterator, I::Item: AsRef<OsStr>,

Tries each candidate in turn with open, returning the first library that loads, or the last error if none does.

Useful for libraries whose file name differs across platforms or versions:

// SAFETY: zlib has no unsound initialisers.
let zlib = unsafe { Library::open_first(["libz.so.1", "libz.1.dylib", "zlib1.dll"]) };

Safety

Same as open, for every candidate.

pub fn this() -> Result<Self>

Returns a handle to the running program.

On Unix this is dlopen(NULL, ..), which looks symbols up in the main program and every library loaded with global visibility (including libc). On Windows it is the executable module, which only exposes symbols the executable itself exports.

Examples found in repository

examples/bindings.rs (line 29)

fn main() -> dlsym::Result<()> {
    #[cfg(not(windows))]
    let lib = Library::this()?;
    // SAFETY: msvcrt is a system library.
    #[cfg(windows)]
    let lib = unsafe { Library::open("msvcrt.dll") }?;
    // Resolves every symbol now; a missing non-optional one is an error.
    let libc = LibC::load(lib)?;

    println!("labs(-42) = {}", libc.labs(-42));
    // SAFETY: valid C strings.
    unsafe {
        println!("strlen(\"dlsym\") = {}", libc.strlen(c"dlsym".as_ptr()));
        println!("atoi(\"123\") = {}", libc.atoi(c"123".as_ptr()));
    }

    let mut buf = [0 as c_char; 32];
    // SAFETY: the buffer is large enough and the format matches.
    unsafe {
        libc.sprintf()
            .with(|f| f(buf.as_mut_ptr(), c"%05.1f".as_ptr(), 2.5f64))
    };
    // SAFETY: `sprintf` NUL-terminated the buffer.
    println!("sprintf = {:?}", unsafe { CStr::from_ptr(buf.as_ptr()) });

    // SAFETY: never called with a null pointer here; we only check presence.
    match unsafe { libc.strlcpy(buf.as_mut_ptr(), c"x".as_ptr(), buf.len()) } {
        Some(n) => println!("strlcpy is available ({n})"),
        None => println!("strlcpy is not available in this C library"),
    }
    Ok(())
}

examples/symbols.rs (line 40)

fn main() -> dlsym::Result<()> {
    // SAFETY: the C math library's initialisers are trusted.
    let libm = unsafe { Library::open(LIBM) }?;

    // SAFETY: `cos` has this signature.
    let cos = unsafe { libm.get::<unsafe extern "C" fn(f64) -> f64>(c"cos") }?;
    // SAFETY: `cos` is defined for every `f64`.
    println!("cos(0) = {}", unsafe { cos.call((0.0,)) });

    // Variadic functions are called through `with`; the raw function
    // pointer cannot escape the closure without `unsafe`.
    #[cfg(not(windows))]
    let libc = Library::this()?;
    // SAFETY: msvcrt is a system library.
    #[cfg(windows)]
    let libc = unsafe { Library::open("msvcrt.dll") }?;
    // SAFETY: `sprintf` has this signature.
    let sprintf = unsafe {
        libc.get::<unsafe extern "C" fn(*mut c_char, *const c_char, ...) -> c_int>(c"sprintf")
    }?;
    let mut buf = [0 as c_char; 64];
    // SAFETY: the buffer is large enough and the format matches.
    unsafe {
        sprintf.with(|f| {
            f(
                buf.as_mut_ptr(),
                c"%s has %d symbols".as_ptr(),
                c"this example".as_ptr(),
                2,
            )
        })
    };
    // SAFETY: `sprintf` NUL-terminated the buffer.
    let text = unsafe { CStr::from_ptr(buf.as_ptr()) };
    println!("{}", text.to_string_lossy());

    // `cos` borrows `libm`: uncommenting this line makes the call below a
    // compile error instead of a use-after-unload.
    // drop(libm);
    // SAFETY: as above.
    println!("cos(pi) = {}", unsafe { cos.call((std::f64::consts::PI,)) });
    Ok(())
}

pub unsafe fn get<T: SymbolType>( &self, name: impl SymbolName, ) -> Result<Symbol<'_, T>>

Looks up a symbol, borrowing the library for as long as the returned Symbol is alive.

Safety

T must match the symbol’s actual type: the right signature and calling convention for functions, the right pointee for data. A mismatch is undefined behaviour once the symbol is used.

Examples found in repository

examples/symbols.rs (line 33)

fn main() -> dlsym::Result<()> {
    // SAFETY: the C math library's initialisers are trusted.
    let libm = unsafe { Library::open(LIBM) }?;

    // SAFETY: `cos` has this signature.
    let cos = unsafe { libm.get::<unsafe extern "C" fn(f64) -> f64>(c"cos") }?;
    // SAFETY: `cos` is defined for every `f64`.
    println!("cos(0) = {}", unsafe { cos.call((0.0,)) });

    // Variadic functions are called through `with`; the raw function
    // pointer cannot escape the closure without `unsafe`.
    #[cfg(not(windows))]
    let libc = Library::this()?;
    // SAFETY: msvcrt is a system library.
    #[cfg(windows)]
    let libc = unsafe { Library::open("msvcrt.dll") }?;
    // SAFETY: `sprintf` has this signature.
    let sprintf = unsafe {
        libc.get::<unsafe extern "C" fn(*mut c_char, *const c_char, ...) -> c_int>(c"sprintf")
    }?;
    let mut buf = [0 as c_char; 64];
    // SAFETY: the buffer is large enough and the format matches.
    unsafe {
        sprintf.with(|f| {
            f(
                buf.as_mut_ptr(),
                c"%s has %d symbols".as_ptr(),
                c"this example".as_ptr(),
                2,
            )
        })
    };
    // SAFETY: `sprintf` NUL-terminated the buffer.
    let text = unsafe { CStr::from_ptr(buf.as_ptr()) };
    println!("{}", text.to_string_lossy());

    // `cos` borrows `libm`: uncommenting this line makes the call below a
    // compile error instead of a use-after-unload.
    // drop(libm);
    // SAFETY: as above.
    println!("cos(pi) = {}", unsafe { cos.call((std::f64::consts::PI,)) });
    Ok(())
}

pub unsafe fn get_arc<T: SymbolType>( self: &Arc<Self>, name: impl SymbolName, ) -> Result<ArcSymbol<T>>

Looks up a symbol, keeping the library alive through the Arc rather than a borrow. Useful for storing symbols in 'static contexts.

Safety

Same as get.

pub fn path(&self) -> Option<PathBuf>

Returns the path the library was loaded from, if the platform can tell (glibc, Apple platforms and Windows). For Library::this, this is the executable.

pub fn leak(self) -> &'static Library

Keeps the library loaded for the rest of the program, so symbols borrowed from it are 'static.

pub fn close(self) -> Result<()>

Unloads the library, reporting any error from the loader. Dropping a Library does the same but ignores errors.

Trait Implementations

impl Debug for Library

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Library

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl LibraryExt for Library

unsafe fn get_versioned<T: SymbolType>( &self, name: impl SymbolName, version: impl SymbolName, ) -> Result<Symbol<'_, T>>

Looks up a specific version of a symbol (dlvsym), such as ("memcpy", "GLIBC_2.2.5").