pub struct Library(/* private fields */);
Expand description
A loaded dynamic library.
Implementations§
source§impl Library
impl Library
sourcepub unsafe fn new<P: AsRef<OsStr>>(filename: P) -> Result<Library, Error>
pub unsafe fn new<P: AsRef<OsStr>>(filename: P) -> Result<Library, Error>
Find and load a dynamic library.
The filename
argument may be either:
- A library filename;
- The absolute path to the library;
- A relative (to the current working directory) path to the library.
§Safety
When a library is loaded, initialisation routines contained within it are executed. For the purposes of safety, the execution of these routines is conceptually the same calling an unknown foreign function and may impose arbitrary requirements on the caller for the call to be sound.
Additionally, the callers of this function must also ensure that execution of the termination routines contained within the library is safe as well. These routines may be executed when the library is unloaded.
§Thread-safety
The implementation strives to be as MT-safe as sanely possible, however on certain
platforms the underlying error-handling related APIs not always MT-safe. This library
shares these limitations on those platforms. In particular, on certain UNIX targets
dlerror
is not MT-safe, resulting in garbage error messages in certain MT-scenarios.
Calling this function from multiple threads is not MT-safe if used in conjunction with
library 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, the locations in which the library is searched are
platform specific and cannot be adjusted in a portable manner. See the documentation for
the platform specific os::unix::Library::new
and os::windows::Library::new
methods
for further information on library lookup behaviour.
If the filename
specifies a library filename without a path and with the extension omitted,
the .dll
extension is implicitly added on Windows.
§Tips
Distributing your dynamic libraries under a filename common to all platforms (e.g.
awesome.module
) allows you 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.
unsafe {
let _ = Library::new("/path/to/awesome.module").unwrap();
let _ = Library::new("../awesome.module").unwrap();
let _ = Library::new("libsomelib.so.1").unwrap();
}
sourcepub unsafe fn get<T>(&self, symbol: &[u8]) -> Result<Symbol<'_, T>, Error>
pub unsafe fn get<T>(&self, symbol: &[u8]) -> Result<Symbol<'_, T>, Error>
Get a pointer to a function or static variable by symbol name.
The symbol
may not contain any null bytes, with the exception of the last byte. Providing a
null-terminated symbol
may help to avoid an allocation.
The symbol is interpreted as-is; no mangling is done. This means that symbols like x::y
are
most likely invalid.
§Safety
Users of this API must specify the correct type of the function or variable loaded.
§Platform-specific behaviour
The implementation of thread-local variables is extremely platform specific and uses of such variables that work on e.g. Linux may have unintended behaviour on other targets.
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 null pointer is something you care about,
consider using the os::unix::Library::get_singlethreaded
call.
§Examples
Given a loaded library:
let lib = unsafe {
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;
};
sourcepub fn close(self) -> Result<(), Error>
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.
The underlying data structures may still get leaked if an error does occur.