libloading/
lib.rs

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

libloading/
lib.rs
