| 1 |
//! Bindings around the platform's dynamic library loading primitives with greatly improved memory safety. |
| 2 |
//! |
| 3 |
//! Using this library allows the loading of [dynamic libraries](struct.Library.html), also known as |
| 4 |
//! shared libraries, and the use of the functions and static variables they contain. |
| 5 |
//! |
| 6 |
//! The `libloading` crate exposes a cross-platform interface to load a library and make use of its |
| 7 |
//! contents, but little is done to hide the differences in behaviour between platforms. |
| 8 |
//! The API documentation strives to document such differences as much as possible. |
| 9 |
//! |
| 10 |
//! Platform-specific APIs are also available in the [`os`](crate::os) module. These APIs are more |
| 11 |
//! flexible, but less safe. |
| 12 |
//! |
| 13 |
//! # Installation |
| 14 |
//! |
| 15 |
//! Add the `libloading` library to your dependencies in `Cargo.toml`: |
| 16 |
//! |
| 17 |
//! ```toml |
| 18 |
//! [dependencies] |
| 19 |
//! libloading = "0.8" |
| 20 |
//! ``` |
| 21 |
//! |
| 22 |
//! # Usage |
| 23 |
//! |
| 24 |
//! In your code, run the following: |
| 25 |
//! |
| 26 |
//! ```no_run |
| 27 |
//! fn call_dynamic() -> Result<u32, Box<dyn std::error::Error>> { |
| 28 |
//! unsafe { |
| 29 |
//! let lib = libloading::Library::new("/path/to/liblibrary.so")?; |
| 30 |
//! let func: libloading::Symbol<unsafe extern fn() -> u32> = lib.get(b"my_func")?; |
| 31 |
//! Ok(func()) |
| 32 |
//! } |
| 33 |
//! } |
| 34 |
//! ``` |
| 35 |
//! |
| 36 |
//! The compiler will ensure that the loaded function will not outlive the `Library` from which it comes, |
| 37 |
//! preventing the most common memory-safety issues. |
| 38 |
#![cfg_attr(any(unix, windows), deny(missing_docs, clippy::all, unreachable_pub, unused))] |
| 39 |
#![cfg_attr(libloading_docs, feature(doc_cfg))] |
| 40 |
|
| 41 |
pub mod changelog; |
| 42 |
pub mod os; |
| 43 |
mod util; |
| 44 |
mod error; |
| 45 |
#[cfg(any(unix, windows, libloading_docs))] |
| 46 |
mod safe; |
| 47 |
|
| 48 |
pub use self::error::Error; |
| 49 |
#[cfg(any(unix, windows, libloading_docs))] |
| 50 |
pub use self::safe::{Library, Symbol}; |
| 51 |
use std::env::consts::{DLL_PREFIX, DLL_SUFFIX}; |
| 52 |
use std::ffi::{OsStr, OsString}; |
| 53 |
|
| 54 |
/// Converts a library name to a filename generally appropriate for use on the system. |
| 55 |
/// |
| 56 |
/// This function will prepend prefixes (such as `lib`) and suffixes (such as `.so`) to the library |
| 57 |
/// `name` to construct the filename. |
| 58 |
/// |
| 59 |
/// # Examples |
| 60 |
/// |
| 61 |
/// It can be used to load global libraries in a platform independent manner: |
| 62 |
/// |
| 63 |
/// ``` |
| 64 |
/// use libloading::{Library, library_filename}; |
| 65 |
/// // Will attempt to load `libLLVM.so` on Linux, `libLLVM.dylib` on macOS and `LLVM.dll` on |
| 66 |
/// // Windows. |
| 67 |
/// let library = unsafe { |
| 68 |
/// Library::new(library_filename("LLVM")) |
| 69 |
/// }; |
| 70 |
/// ``` |
| 71 |
pub fn library_filename<S: AsRef<OsStr>>(name: S) -> OsString { |
| 72 |
let name = name.as_ref(); |
| 73 |
let mut string = OsString::with_capacity(name.len() + DLL_PREFIX.len() + DLL_SUFFIX.len()); |
| 74 |
string.push(DLL_PREFIX); |
| 75 |
string.push(name); |
| 76 |
string.push(DLL_SUFFIX); |
| 77 |
string |
| 78 |
} |