Struct dlib::Library

pub struct Library(_);

A loaded dynamic library.

Implementations

impl Library

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

Find and load a dynamic library.

The filename argument may be any of:

• A library filename;
• Absolute path to the library;
• Relative (to the current working directory) path to the library.

Thread-safety

The implementation strives to be as MT-safe as sanely possible, however due to certain error-handling related resources not always being safe, this library is not MT-safe either.

• On Windows Vista and earlier error handling falls back to SetErrorMode, which is not MT-safe. MT-scenarios involving this function may cause a traditional data race;
• On some UNIX targets dlerror might not be MT-safe, resulting in garbage error messages in certain MT-scenarios.

Calling this function from multiple threads is not safe if used in conjunction with relative filenames and the library search path is modified (SetDllDirectory function on Windows, {DY,}LD_LIBRARY_PATH environment variable on UNIX).

Platform-specific behaviour

When a plain library filename is supplied, locations where library is searched for is platform specific and cannot be adjusted in a portable manner. See documentation for the platform specific os::unix::Library::new and [os::windows::Library::new] methods for further information on library lookup behaviour.

Windows

If the filename specifies a library filename without path and with extension omitted, .dll extension is implicitly added. This behaviour may be suppressed by appending a trailing . to the filename.

If the library contains thread local variables (MSVC’s _declspec(thread), Rust’s #[thread_local] attributes), loading the library will fail on versions prior to Windows Vista.

Tips

Distributing your dynamic libraries under a filename common to all platforms (e.g. awesome.module) allows to avoid code which has to account for platform’s conventional library filenames.

Strive to specify an absolute or at least a relative path to your library, unless system-wide libraries are being loaded. Platform-dependent library search locations combined with various quirks related to path-less filenames may cause flakiness in programs.

Examples

// Any of the following are valid.
let _ = Library::new("/path/to/awesome.module").unwrap();
let _ = Library::new("../awesome.module").unwrap();
let _ = Library::new("libsomelib.so.1").unwrap();

pub unsafe fn get<T>(
    &'lib self,
    symbol: &[u8]
) -> Result<Symbol<'lib, 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

Pointer to a value of arbitrary type is returned. Using a value with wrong type is undefined.

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 or Windows.

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 os::unix::Library::get_singlethreaded call.

Examples

Given a loaded library:

let lib = Library::new("/path/to/awesome.module").unwrap();

Loading and using a function looks like this:

unsafe {
    let awesome_function: Symbol<unsafe extern fn(f64) -> f64> =
        lib.get(b"awesome_function\0").unwrap();
    awesome_function(0.42);
}

A static variable may also be loaded and inspected:

unsafe {
    let awesome_variable: Symbol<*mut f64> = lib.get(b"awesome_variable\0").unwrap();
    **awesome_variable = 42.0;
};

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.

Trait Implementations

impl Debug for Library

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

Formats the value using the given formatter.

impl From<Library> for Library

fn from(lib: Library) -> Library

Performs the conversion.

impl Send for Library

impl Sync for Library