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