libloading 0.9.0

//! Bindings around the platform's dynamic library loading primitives with greatly improved memory safety.
//!
//! Using this library allows the loading of [dynamic libraries](struct.Library.html), also known as
//! shared libraries, and the use of the functions and static variables they contain.
//!
//! The `libloading` crate exposes a cross-platform interface to load a library and make use of its
//! contents, but little is done to hide the differences in behaviour between platforms.
//! The API documentation strives to document such differences as much as possible.
//!
//! Platform-specific APIs are also available in the [`os`] module. These APIs are more
//! flexible, but less safe.
//!
//! # Installation
//!
//! Add the `libloading` library to your dependencies in `Cargo.toml`:
//!
//! ```toml
//! [dependencies]
//! libloading = "0.8"
//! ```
//!
//! # Usage
//!
//! In your code, run the following:
//!
//! ```no_run
//! fn call_dynamic() -> Result<u32, Box<dyn std::error::Error>> {
//!     unsafe {
//!         let lib = libloading::Library::new("/path/to/liblibrary.so")?;
//!         let func: libloading::Symbol<unsafe extern "C" fn() -> u32> = lib.get(b"my_func")?;
//!         Ok(func())
//!     }
//! }
//! ```
//!
//! The compiler will ensure that the loaded function will not outlive the `Library` from which it comes,
//! preventing the most common memory-safety issues.
#![cfg_attr(
    any(unix, windows),
    deny(missing_docs, clippy::all, unreachable_pub, unused)
)]
#![cfg_attr(libloading_docs, feature(doc_cfg))]
#![no_std]

extern crate alloc;
#[cfg(feature = "std")]
extern crate std;

mod as_filename;
mod as_symbol_name;

pub use as_filename::AsFilename;
pub use as_symbol_name::AsSymbolName;

pub mod changelog;
mod error;
pub mod os;
#[cfg(any(unix, windows, libloading_docs))]
mod safe;
mod util;

pub use self::error::Error;

#[cfg(any(unix, windows, libloading_docs))]
pub use self::safe::{Library, Symbol};

/// Converts a library name to a filename generally appropriate for use on the system.
///
/// This function will prepend prefixes (such as `lib`) and suffixes (such as `.so`) to the library
/// `name` to construct the filename.
///
/// # Examples
///
/// It can be used to load global libraries in a platform independent manner:
///
/// ```
/// use libloading::{Library, library_filename};
/// // Will attempt to load `libLLVM.so` on Linux, `libLLVM.dylib` on macOS and `LLVM.dll` on
/// // Windows.
/// let library = unsafe {
///     Library::new(library_filename("LLVM"))
/// };
/// ```
#[cfg(feature = "std")]
#[cfg_attr(libloading_docs, doc(cfg(feature = "std")))]
pub fn library_filename<S: AsRef<std::ffi::OsStr>>(name: S) -> std::ffi::OsString {
    use std::env::consts::{DLL_PREFIX, DLL_SUFFIX};

    let name = name.as_ref();
    let mut string =
        std::ffi::OsString::with_capacity(name.len() + DLL_PREFIX.len() + DLL_SUFFIX.len());
    string.push(DLL_PREFIX);
    string.push(name);
    string.push(DLL_SUFFIX);
    string
}