Struct libloading::Library [−] [src]

pub struct Library(_);

A loaded dynamic library.

Methods

impl Library
[src]

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

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.

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.

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

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 absolute or relative path to your library. Platform-dependent library search locations combined with various quirks related to path-less filenames makes for a very flaky code.

Examples

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

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

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

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

Platform-specific behaviour

On Linux and Windows, a TLS variable acts just like any regular static variable. OS X uses some sort of lazy initialization scheme, which makes loading TLS variables this way impossible. Using a TLS variable loaded this way on OS X is undefined behaviour.

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;
};

Trait Implementations

impl Debug for Library
[src]

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

Formats the value using the given formatter.

impl From<Library> for Library
[src]

fn from(lib: Library) -> Library

Performs the conversion.