Struct dlopen::symbor::Library

pub struct Library { /* fields omitted */ }

Safe wrapper around dynamic link library handle.

Methods of Library return only types that make the library borrowed. Therefore the problem with dangling symbols is prevented.

Note:: It is recommended that you use certain methods in certain situations:

• symbol() - for obtaining functions and pointers (but only if you can't use references instead of pointers and you do not accept null value of a pointer).
• reference() and reference_mut() - for obtaining access to statically allocated objects - either constant or mutable.
• ptr_or_null() and ptr_or_null_mut() - for obtaining pointers if you accept null values of pointers (in 99% of cases you should rather use previously mentioned methods).

Example

extern crate dlopen;
use dlopen::symbor::Library;

fn main(){
    let lib = Library::open("libexample.dylib").unwrap();
    let fun = unsafe{lib.symbol::<unsafe extern "C" fn()>("function")}.unwrap();
    unsafe{fun()};
    let glob_val: &mut u32 = unsafe{lib.reference_mut("glob_val")}.unwrap();
    *glob_val = 42;
    let ptr_or_null = unsafe{lib.ptr_or_null::<()>("void_ptr")}.unwrap();
    println!("Pointer is null: {}", ptr_or_null.is_null());
}

Methods

impl Library

fn open<S>(name: S) -> Result<Library, Error> where
    S: AsRef<OsStr>, 

Open dynamic link library using provided file name or path.

unsafe fn symbol<T>(&self, name: &str) -> Result<Symbol<T>, Error>

Obtain a symbol from library.

This method is the most general one and allows obtaining basically everything assuming that the value of the given symbol cannot be null (use ptr_or_null() for this case). However the reference() and reference_mut() methods return a native reference and they are more programmer friendly when you try accessing statically allocated data in the library.

unsafe fn symbol_cstr<T>(&self, name: &CStr) -> Result<Symbol<T>, Error>

Equivalent of the symbol() method but takes CStr as a argument.

unsafe fn ptr_or_null<T>(&self, name: &str) -> Result<PtrOrNull<T>, Error>

Obtain a const pointer from library.

Note: This method is only recommended for data that can't be accessed as a reference and that can have a null pointer value (so not in 99% of cases).

unsafe fn ptr_or_null_cstr<T>(&self, name: &CStr) -> Result<PtrOrNull<T>, Error>

Equivalent of the pointer() method but takes CStr as a argument.

unsafe fn ptr_or_null_mut<T>(
    &self,
    name: &str
) -> Result<PtrOrNullMut<T>, Error>

Obtain a mutable pointer from library.

Note: This method is only recommended for data that can't be accessed as a reference and that can have a null pointer value (so not in 99% of cases).

unsafe fn ptr_or_null_mut_cstr<T>(
    &self,
    name: &CStr
) -> Result<PtrOrNullMut<T>, Error>

Equivalent of the pointer_mut() method but takes CStr as a argument.

unsafe fn reference<T>(&self, name: &str) -> Result<&T, Error>

Obtain const reference to statically allocated data in the library.

unsafe fn reference_cstr<T>(&self, name: &CStr) -> Result<&T, Error>

Equivalent of the reference() method but takes CStr as a argument.

unsafe fn reference_mut<T>(&self, name: &str) -> Result<&mut T, Error>

Obtain mutable reference to statically allocated data in the library.

unsafe fn reference_mut_cstr<T>(&self, name: &CStr) -> Result<&mut T, Error>

Equivalent of the reference_mut() method but takes CStr as a argument.

Trait Implementations

impl Send for Library

impl Sync for Library