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
41 pub mod changelog;
42 pub mod os;
43 mod util;
44
45 mod error;
46 pub use self::error::Error;
47
48 #[cfg(any(unix, windows, libloading_docs))]
49 mod safe;
50 #[cfg(any(unix, windows, libloading_docs))]
51 pub use self::safe::{Library, Symbol};
52
53 use std::env::consts::{DLL_PREFIX, DLL_SUFFIX};
54 use 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 /// ```
library_filename<S: AsRef<OsStr>>(name: S) -> OsString73 pub 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