libloading/
lib.rs

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(
39    any(unix, windows),
40    deny(missing_docs, clippy::all, unreachable_pub, unused)
41)]
42#![cfg_attr(libloading_docs, feature(doc_cfg))]
43
44pub mod changelog;
45mod error;
46pub mod os;
47#[cfg(any(unix, windows, libloading_docs))]
48mod safe;
49mod util;
50
51pub use self::error::Error;
52#[cfg(any(unix, windows, libloading_docs))]
53pub use self::safe::{Library, Symbol};
54use std::env::consts::{DLL_PREFIX, DLL_SUFFIX};
55use std::ffi::{OsStr, OsString};
56
57/// Converts a library name to a filename generally appropriate for use on the system.
58///
59/// This function will prepend prefixes (such as `lib`) and suffixes (such as `.so`) to the library
60/// `name` to construct the filename.
61///
62/// # Examples
63///
64/// It can be used to load global libraries in a platform independent manner:
65///
66/// ```
67/// use libloading::{Library, library_filename};
68/// // Will attempt to load `libLLVM.so` on Linux, `libLLVM.dylib` on macOS and `LLVM.dll` on
69/// // Windows.
70/// let library = unsafe {
71///     Library::new(library_filename("LLVM"))
72/// };
73/// ```
74pub fn library_filename<S: AsRef<OsStr>>(name: S) -> OsString {
75    let name = name.as_ref();
76    let mut string = OsString::with_capacity(name.len() + DLL_PREFIX.len() + DLL_SUFFIX.len());
77    string.push(DLL_PREFIX);
78    string.push(name);
79    string.push(DLL_SUFFIX);
80    string
81}
libloading/lib.rs

libloading/
lib.rs
