Merge branch 'nstd.os.unix.shared_lib'

Author: RustEnthusiast

Cargo.toml

@@ -33,6 +33,7 @@ nstd_heap_ptr = ["nstd_alloc", "nstd_core"]
 nstd_io = ["nstd_alloc", "nstd_core", "nstd_string", "nstd_vec", "std"]
 nstd_math = ["std"]
 nstd_os = []
+nstd_os_unix_shared_lib = ["libc", "nstd_core", "nstd_os"]
 nstd_os_windows_alloc = [
     "nstd_core", "nstd_os", "windows-sys/Win32_Foundation", "windows-sys/Win32_System_Memory"
 ]
@@ -44,5 +45,8 @@ nstd_vec = ["nstd_alloc", "nstd_core"]
 [dependencies]
 libloading = { version = "0.7", optional = true }
 
+[target.'cfg(target_family = "unix")'.dependencies]
+libc = { version = "0.2", optional = true, default-features = false }
+
 [target.'cfg(target_os = "windows")'.dependencies]
 windows-sys = { version = "0.42", optional = true }

README.md

@@ -49,6 +49,8 @@ int main()
         - `stdout` - A handle to the standard output stream.
     - `math` - High level math operations.
     - `os` - Operating system specific functionality.
+        - `unix` - Low level Unix like operating system support.
+            - `shared_lib` - Provides shared library access for Unix like systems.
         - `windows` - OS support for Windows.
             - `alloc` - Low level memory allocation for Windows.
                 - `heap` - Process heap management for Windows.

include/nstd/os.h

@@ -1,5 +1,6 @@
 #ifndef NSTD_OS_H
 #define NSTD_OS_H
 #include "os/os.h"
+#include "os/unix.h"
 #include "os/windows.h"
 #endif

include/nstd/os/unix.h

@@ -0,0 +1,4 @@
+#ifndef NSTD_OS_UNIX_H
+#define NSTD_OS_UNIX_H
+#include "unix/shared_lib.h"
+#endif

include/nstd/os/unix/shared_lib.h

@@ -0,0 +1,75 @@
+#ifndef NSTD_OS_UNIX_SHARED_LIB_H
+#define NSTD_OS_UNIX_SHARED_LIB_H
+#include "../../core/optional.h"
+#include "../../nstd.h"
+
+/// Represents an owned handle to a dynamically loaded library.
+typedef struct {
+    /// A raw handle to the shared library.
+    NSTDAnyMut handle;
+} NSTDUnixSharedLib;
+
+/// Represents an optional `NSTDUnixSharedLib`.
+NSTDOptional(NSTDUnixSharedLib) NSTDUnixOptionalSharedLib;
+
+/// Loads a dynamically loaded shared library.
+///
+/// # Parameters:
+///
+/// - `const NSTDChar *path` - A path to the shared library to load.
+///
+/// # Returns
+///
+/// `NSTDUnixOptionalSharedLib lib` - A handle to the loaded library.
+///
+/// # Safety
+///
+/// See <https://man7.org/linux/man-pages/man3/dlopen.3.html>.
+NSTDAPI NSTDUnixOptionalSharedLib nstd_os_unix_shared_lib_load(const NSTDChar *path);
+
+/// Returns an immutable opaque pointer to a symbol in a loaded library.
+///
+/// # Parameters:
+///
+/// - `const NSTDUnixSharedLib *lib` - The shared library.
+///
+/// - `const NSTDChar *symbol` - The symbol to retrieve a pointer to.
+///
+/// # Returns
+///
+/// `NSTDAny ptr` - A pointer to the loaded symbol, null on error.
+///
+/// # Safety
+///
+/// See <https://man7.org/linux/man-pages/man3/dlsym.3.html>.
+NSTDAPI NSTDAny nstd_os_unix_shared_lib_get(const NSTDUnixSharedLib *lib, const NSTDChar *symbol);
+
+/// Returns a mutable opaque pointer to a symbol in a loaded library.
+///
+/// # Parameters:
+///
+/// - `NSTDUnixSharedLib *lib` - The shared library.
+///
+/// - `const NSTDChar *symbol` - The symbol to retrieve a pointer to.
+///
+/// # Returns
+///
+/// `NSTDAnyMut ptr` - A pointer to the loaded symbol, null on error.
+///
+/// # Safety
+///
+/// See <https://man7.org/linux/man-pages/man3/dlsym.3.html>.
+NSTDAPI NSTDAnyMut nstd_os_unix_shared_lib_get_mut(NSTDUnixSharedLib *lib, const NSTDChar *symbol);
+
+/// Closes and frees a loaded shared library.
+///
+/// # Parameters:
+///
+/// - `NSTDUnixSharedLib lib` - A handle to the loaded library to unload.
+///
+/// # Safety
+///
+/// See <https://man7.org/linux/man-pages/man3/dlclose.3p.html>.
+NSTDAPI void nstd_os_unix_shared_lib_free(NSTDUnixSharedLib lib);
+
+#endif

src/os.rs

@@ -1,4 +1,6 @@
 //! Operating system specific functionality.
+#[cfg(target_family = "unix")]
+pub mod unix;
 #[cfg(target_os = "windows")]
 pub mod windows;
 

src/os/unix.rs

@@ -0,0 +1,4 @@
+//! Low level Unix like operating system support.
+#[cfg(feature = "nstd_os_unix_shared_lib")]
+#[cfg_attr(doc_cfg, doc(cfg(feature = "nstd_os_unix_shared_lib")))]
+pub mod shared_lib;

src/os/unix/shared_lib.rs

@@ -0,0 +1,108 @@
+//! Provides shared library access for Unix like systems.
+use crate::{core::optional::NSTDOptional, NSTDAny, NSTDAnyMut, NSTDChar};
+use libc::{dlclose, dlopen, dlsym, RTLD_LAZY, RTLD_LOCAL};
+
+/// Represents an owned handle to a dynamically loaded library.
+#[repr(C)]
+pub struct NSTDUnixSharedLib {
+    /// A raw handle to the shared library.
+    handle: NSTDAnyMut,
+}
+impl Drop for NSTDUnixSharedLib {
+    /// [NSTDUnixSharedLib]'s destructor.
+    #[inline]
+    fn drop(&mut self) {
+        // SAFETY: `self.handle` is never null.
+        unsafe { dlclose(self.handle) };
+    }
+}
+
+/// Represents an optional `NSTDUnixSharedLib`.
+pub type NSTDUnixOptionalSharedLib = NSTDOptional<NSTDUnixSharedLib>;
+
+/// Loads a dynamically loaded shared library.
+///
+/// # Parameters:
+///
+/// - `const NSTDChar *path` - A path to the shared library to load.
+///
+/// # Returns
+///
+/// `NSTDUnixOptionalSharedLib lib` - A handle to the loaded library.
+///
+/// # Safety
+///
+/// See <https://man7.org/linux/man-pages/man3/dlopen.3.html>.
+#[inline]
+#[cfg_attr(feature = "clib", no_mangle)]
+pub unsafe extern "C" fn nstd_os_unix_shared_lib_load(
+    path: *const NSTDChar,
+) -> NSTDUnixOptionalSharedLib {
+    let handle = dlopen(path, RTLD_LAZY | RTLD_LOCAL);
+    if handle.is_null() {
+        return NSTDOptional::None;
+    }
+    NSTDOptional::Some(NSTDUnixSharedLib { handle })
+}
+
+/// Returns an immutable opaque pointer to a symbol in a loaded library.
+///
+/// # Parameters:
+///
+/// - `const NSTDUnixSharedLib *lib` - The shared library.
+///
+/// - `const NSTDChar *symbol` - The symbol to retrieve a pointer to.
+///
+/// # Returns
+///
+/// `NSTDAny ptr` - A pointer to the loaded symbol, null on error.
+///
+/// # Safety
+///
+/// See <https://man7.org/linux/man-pages/man3/dlsym.3.html>.
+#[inline]
+#[cfg_attr(feature = "clib", no_mangle)]
+pub unsafe extern "C" fn nstd_os_unix_shared_lib_get(
+    lib: &NSTDUnixSharedLib,
+    symbol: *const NSTDChar,
+) -> NSTDAny {
+    dlsym(lib.handle, symbol)
+}
+
+/// Returns a mutable opaque pointer to a symbol in a loaded library.
+///
+/// # Parameters:
+///
+/// - `NSTDUnixSharedLib *lib` - The shared library.
+///
+/// - `const NSTDChar *symbol` - The symbol to retrieve a pointer to.
+///
+/// # Returns
+///
+/// `NSTDAnyMut ptr` - A pointer to the loaded symbol, null on error.
+///
+/// # Safety
+///
+/// See <https://man7.org/linux/man-pages/man3/dlsym.3.html>.
+#[inline]
+#[cfg_attr(feature = "clib", no_mangle)]
+pub unsafe extern "C" fn nstd_os_unix_shared_lib_get_mut(
+    lib: &mut NSTDUnixSharedLib,
+    symbol: *const NSTDChar,
+) -> NSTDAnyMut {
+    dlsym(lib.handle, symbol)
+}
+
+/// Closes and frees a loaded shared library.
+///
+/// # Parameters:
+///
+/// - `NSTDUnixSharedLib lib` - A handle to the loaded library to unload.
+///
+/// # Safety
+///
+/// See <https://man7.org/linux/man-pages/man3/dlclose.3p.html>.
+#[inline]
+#[cfg_attr(feature = "clib", no_mangle)]
+#[allow(unused_variables)]
+pub unsafe extern "C" fn nstd_os_unix_shared_lib_free(lib: NSTDUnixSharedLib) {}

test.py

@@ -1,8 +1,8 @@
 import os
 
 FEATURES = ("nstd_alloc", "nstd_core", "nstd_cstring", "nstd_fs", "nstd_heap_ptr", "nstd_io",
-            "nstd_math", "nstd_os_windows_alloc", "nstd_shared_lib", "nstd_shared_ptr",
-            "nstd_string", "nstd_vec")
+            "nstd_math", "nstd_os_unix_shared_lib", "nstd_os_windows_alloc", "nstd_shared_lib",
+            "nstd_shared_ptr", "nstd_string", "nstd_vec")
 
 TARGETS = ("x86_64-pc-windows-msvc", "x86_64-apple-darwin",
            "x86_64-unknown-linux-gnu", "x86_64-apple-ios", "x86_64-linux-android")