Struct libloading::os::unix::Library

pub struct Library { /* fields omitted */ }

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

Implementations

impl Library

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

Find and eagerly load a shared library (module).

If the filename contains a path separator, the filename is interpreted as a path to a file. Otherwise, platform-specific algorithms are employed to find a library with a matching file name.

This is equivalent to Library::open(filename, RTLD_NOW).

pub fn this() -> Library

Eagerly load the Library representing the current executable.

Library::get calls of the returned Library will look for symbols in following locations in order:

1. Original program image;
2. Any executable object files (e.g. shared libraries) loaded at program startup;
3. Executable object files loaded at runtime (e.g. via other Library::new calls or via calls to the dlopen function)

Note that behaviour of Library loaded with this method is different from Libraries loaded with os::windows::Library::this.

This is equivalent to Library::open(None, RTLD_NOW).

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

Find and load an executable object file (shared library).

See documentation for Library::this for further description of behaviour when the filename is None. Otherwise see Library::new.

Corresponds to dlopen(filename, flags).

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 an allocation in some cases.

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

Safety

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 defined behaviour.

Platform-specific behaviour

Implementation of thread local variables is extremely platform specific and uses of these variables that work on e.g. Linux may have unintended behaviour on other POSIX systems.

On POSIX implementations where the dlerror function is not confirmed to be MT-safe (such as FreeBSD), this function will unconditionally return an error when 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 symbol at null address is something you care about, consider using the Library::get_singlethreaded call.

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.

Safety

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 defined behaviour.

It is up to the user of this library to ensure that no other calls to an MT-unsafe implementation of dlerror occur during execution of this function. Failing that, the behaviour of this function is not defined.

Platform-specific behaviour

Implementation of thread local variables is extremely platform specific and uses of these variables that work on e.g. Linux may have unintended behaviour on other POSIX systems.

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.

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

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

Safety

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.

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 this will be done when Library is dropped.

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.

impl From<Library> for Library

fn from(lib: Library) -> Library

Performs the conversion.

impl From<Library> for Library

fn from(lib: Library) -> Library

Performs the conversion.

impl Send for Library

impl Sync for Library