pub struct Library { /* private fields */ }Expand description
A platform-specific counterpart of the cross-platform 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 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_LAZY | RTLD_LOCAL).
§Safety
When a library is loaded, initialisation routines contained within the library 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.
sourcepub fn this() -> Library
pub fn this() -> Library
Load the Library representing the current executable.
Library::get calls of the returned Library will look for symbols in following
locations in order:
- The original program image;
- Any executable object files (e.g. shared libraries) loaded at program startup;
- Any executable object files loaded at runtime (e.g. via other
Library::newcalls or via calls to thedlopenfunction).
Note that the behaviour of a Library loaded with this method is different from that of
Libraries loaded with os::windows::Library::this.
This is equivalent to Library::open(None, RTLD_LAZY | RTLD_LOCAL).
sourcepub unsafe fn open<P>(
filename: Option<P>,
flags: c_int,
) -> Result<Library, Error>
pub unsafe fn open<P>( filename: Option<P>, flags: c_int, ) -> Result<Library, Error>
Find and load an executable object file (shared library).
See documentation for Library::this for further description of the behaviour
when the filename is None. Otherwise see Library::new.
Corresponds to dlopen(filename, flags).
§Safety
When a library is loaded, initialisation routines contained within the library 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.
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.
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. Using a
Symbol with a wrong type is undefined.
§Platform-specific behaviour
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 Library::get_singlethreaded call.
sourcepub unsafe fn get_singlethreaded<T>(
&self,
symbol: &[u8],
) -> Result<Symbol<T>, Error>
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 the exception of the last byte. Providing a
null terminated symbol may help to avoid an allocation.
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.
It is up to the user of this library to ensure that no other calls to an MT-unsafe
implementation of dlerror occur during the execution of this function. Failing that, the
behaviour of this function is not defined.
§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.
sourcepub fn into_raw(self) -> *mut c_void
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.
sourcepub unsafe fn from_raw(handle: *mut c_void) -> Library
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.
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.