Struct Library

Source

pub struct Library { /* private fields */ }

Expand description

A platform-specific equivalent of the cross-platform Library.

Implementations§

Source §

impl Library

Source

pub fn new<P: AsRef<OsStr>>(filename: P) -> Result<Library, Error>

Find and load a shared library (module).

Locations where library is searched for is platform specific and can’t be adjusted portably.

Corresponds to dlopen(filename, RTLD_NOW).

Source

pub fn this() -> Library

Load the dynamic libraries linked into main program.

This allows retrieving symbols from any dynamic library linked into the program, without specifying the exact library.

Corresponds to dlopen(NULL, RTLD_NOW).

Source

pub fn open(filename: Option, flags: c_int) -> Result<Library, Error>
where P: AsRef<OsStr>,

Find and load a shared library (module).

Locations where library is searched for is platform specific and can’t be adjusted portably.

If the filename is None, null pointer is passed to dlopen.

Corresponds to dlopen(filename, flags).

Source

pub unsafe fn get<T>(&self, symbol: &[u8]) -> Result<Symbol<T>, Error>

Get a pointer to function or static variable by symbol name.

The symbol may not contain any null bytes, with an exception of last byte. A null terminated symbol may avoid a string allocation in some cases.

Symbol is interpreted as-is; no mangling is done. This means that symbols like x::y are most likely invalid.

§Unsafety

This function does not validate the type T. It is up to the user of this function to ensure that the loaded symbol is in fact a T. Using a value with a wrong type has no definied behaviour.

§Platform-specific behaviour

OS X uses some sort of lazy initialization scheme, which makes loading TLS variables impossible. Using a TLS variable loaded this way on OS X is undefined behaviour.

On POSIX implementations where the dlerror function is not confirmed to be MT-safe (such as FreeBSD), this function will unconditionally return an error the underlying dlsym call returns a null pointer. There are rare situations where dlsym returns a genuine null pointer without it being an error. If loading a null pointer is something you care about, consider using the Library::get_singlethreaded call.

Source

pub unsafe fn get_singlethreaded<T>( &self, symbol: &[u8], ) -> Result<Symbol<T>, Error>

Get a pointer to function or static variable by symbol name.

The symbol may not contain any null bytes, with an exception of last byte. A null terminated symbol may avoid a string allocation in some cases.

Symbol is interpreted as-is; no mangling is done. This means that symbols like x::y are most likely invalid.

§Unsafety

This function does not validate the type T. It is up to the user of this function to ensure that the loaded symbol is in fact a T. Using a value with a wrong type has no definied behaviour.

It is up to the user of this library to ensure that no other calls to an MT-unsafe implementation of dlerror occur while this function is executing. Failing that the results of this function are not defined.

§Platform-specific behaviour

OS X uses some sort of lazy initialization scheme, which makes loading TLS variables impossible. Using a TLS variable loaded this way on OS X is undefined behaviour.

Source

pub fn into_raw(self) -> *mut c_void

Convert the Library to a raw handle.

The handle returned by this function shall be usable with APIs which accept handles as returned by dlopen.

Source

pub unsafe fn from_raw(handle: *mut c_void) -> Library

Convert a raw handle returned by dlopen-family of calls to a Library.

§Unsafety

The pointer shall be a result of a successful call of the dlopen-family of functions or a pointer previously returned by Library::into_raw call. It must be valid to call dlclose with this pointer as an argument.

Source

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

Unload the library.

This method might be a no-op, depending on the flags with which the Library was opened, what library was opened or other platform specifics.

You only need to call this if you are interested in handling any errors that may arise when library is unloaded. Otherwise the implementation of Drop for Library will close the library and ignore the errors were they arise.