nstd_sys/os/unix/
shared_lib.rs

1//! Provides shared library access for Unix like systems.
2use crate::{core::optional::NSTDOptional, NSTDAny, NSTDAnyMut, NSTDChar, NSTD_NULL};
3use libc::{dlclose, dlopen, dlsym, RTLD_LAZY, RTLD_LOCAL};
4use nstdapi::nstdapi;
5
6/// Represents an owned handle to a dynamically loaded library.
7#[nstdapi]
8pub struct NSTDUnixSharedLib {
9    /// A raw handle to the shared library.
10    handle: NSTDAnyMut,
11}
12impl Drop for NSTDUnixSharedLib {
13    /// [`NSTDUnixSharedLib`]'s destructor.
14    #[inline]
15    fn drop(&mut self) {
16        // SAFETY: `self.handle` is valid.
17        unsafe { dlclose(self.handle) };
18    }
19}
20// SAFETY: `NSTDUnixSharedLib` owns a handle to the dynamically loaded library.
21unsafe impl Send for NSTDUnixSharedLib {}
22// SAFETY: `NSTDUnixSharedLib` does not undergo interior mutability.
23unsafe impl Sync for NSTDUnixSharedLib {}
24
25/// Represents an optional `NSTDUnixSharedLib`.
26pub type NSTDUnixOptionalSharedLib = NSTDOptional<NSTDUnixSharedLib>;
27
28/// Loads a dynamically loaded shared library.
29///
30/// # Parameters:
31///
32/// - `const NSTDChar *path` - A path to the shared library to load.
33///
34/// # Returns
35///
36/// `NSTDUnixOptionalSharedLib lib` - A handle to the loaded library.
37///
38/// # Safety
39///
40/// See <https://man7.org/linux/man-pages/man3/dlopen.3.html>.
41#[inline]
42#[nstdapi]
43pub unsafe fn nstd_os_unix_shared_lib_load(path: *const NSTDChar) -> NSTDUnixOptionalSharedLib {
44    match dlopen(path, RTLD_LAZY | RTLD_LOCAL) {
45        NSTD_NULL => NSTDOptional::None,
46        handle => NSTDOptional::Some(NSTDUnixSharedLib { handle }),
47    }
48}
49
50/// Returns a raw handle to a dynamically loaded library.
51///
52/// # Parameters:
53///
54/// - `const NSTDUnixSharedLib *lib` - The shared library.
55///
56/// # Returns
57///
58/// `NSTDAnyMut handle` - A raw handle to the dynamically loaded library.
59#[inline]
60#[nstdapi]
61pub const fn nstd_os_unix_shared_lib_handle(lib: &NSTDUnixSharedLib) -> NSTDAnyMut {
62    lib.handle
63}
64
65/// Returns an immutable opaque pointer to a symbol in a loaded library.
66///
67/// # Parameters:
68///
69/// - `const NSTDUnixSharedLib *lib` - The shared library.
70///
71/// - `const NSTDChar *symbol` - The symbol to retrieve a pointer to.
72///
73/// # Returns
74///
75/// `NSTDAny ptr` - A pointer to the loaded symbol, null on error.
76///
77/// # Safety
78///
79/// See <https://man7.org/linux/man-pages/man3/dlsym.3.html>.
80#[inline]
81#[nstdapi]
82pub unsafe fn nstd_os_unix_shared_lib_get(
83    lib: &NSTDUnixSharedLib,
84    symbol: *const NSTDChar,
85) -> NSTDAny {
86    dlsym(lib.handle, symbol)
87}
88
89/// Returns a mutable opaque pointer to a symbol in a loaded library.
90///
91/// # Parameters:
92///
93/// - `NSTDUnixSharedLib *lib` - The shared library.
94///
95/// - `const NSTDChar *symbol` - The symbol to retrieve a pointer to.
96///
97/// # Returns
98///
99/// `NSTDAnyMut ptr` - A pointer to the loaded symbol, null on error.
100///
101/// # Safety
102///
103/// See <https://man7.org/linux/man-pages/man3/dlsym.3.html>.
104#[inline]
105#[nstdapi]
106pub unsafe fn nstd_os_unix_shared_lib_get_mut(
107    lib: &mut NSTDUnixSharedLib,
108    symbol: *const NSTDChar,
109) -> NSTDAnyMut {
110    dlsym(lib.handle, symbol)
111}
112
113/// Closes and frees a loaded shared library.
114///
115/// # Parameters:
116///
117/// - `NSTDUnixSharedLib lib` - A handle to the loaded library to unload.
118///
119/// # Safety
120///
121/// See <https://man7.org/linux/man-pages/man3/dlclose.3p.html>.
122#[inline]
123#[nstdapi]
124#[allow(
125    unused_variables,
126    clippy::missing_const_for_fn,
127    clippy::needless_pass_by_value
128)]
129pub unsafe fn nstd_os_unix_shared_lib_free(lib: NSTDUnixSharedLib) {}
nstd_sys/os/unix/shared_lib.rs

nstd_sys/os/unix/
shared_lib.rs
