sdl3_sys/generated/
loadso.rs

1//! System-dependent library loading routines.
2//!
3//! Shared objects are code that is programmatically loadable at runtime.
4//! Windows calls these "DLLs", Linux calls them "shared libraries", etc.
5//!
6//! To use them, build such a library, then call [`SDL_LoadObject()`] on it. Once
7//! loaded, you can use [`SDL_LoadFunction()`] on that object to find the address
8//! of its exported symbols. When done with the object, call [`SDL_UnloadObject()`]
9//! to dispose of it.
10//!
11//! Some things to keep in mind:
12//!
13//! - These functions only work on C function names. Other languages may have
14//!   name mangling and intrinsic language support that varies from compiler to
15//!   compiler.
16//! - Make sure you declare your function pointers with the same calling
17//!   convention as the actual library function. Your code will crash
18//!   mysteriously if you do not do this.
19//! - Avoid namespace collisions. If you load a symbol from the library, it is
20//!   not defined whether or not it goes into the global symbol namespace for
21//!   the application. If it does and it conflicts with symbols in your code or
22//!   other shared libraries, you will not get the results you expect. :)
23//! - Once a library is unloaded, all pointers into it obtained through
24//!   [`SDL_LoadFunction()`] become invalid, even if the library is later reloaded.
25//!   Don't unload a library if you plan to use these pointers in the future.
26//!   Notably: beware of giving one of these pointers to atexit(), since it may
27//!   call that pointer after the library unloads.
28
29use super::stdinc::*;
30
31use super::error::*;
32
33unsafe extern "C" {
34    /// Dynamically load a shared object.
35    ///
36    /// ## Parameters
37    /// - `sofile`: a system-dependent name of the object file.
38    ///
39    /// ## Return value
40    /// Returns an opaque pointer to the object handle or NULL on failure; call
41    ///   [`SDL_GetError()`] for more information.
42    ///
43    /// ## Thread safety
44    /// It is safe to call this function from any thread.
45    ///
46    /// ## Availability
47    /// This function is available since SDL 3.2.0.
48    ///
49    /// ## See also
50    /// - [`SDL_LoadFunction`]
51    /// - [`SDL_UnloadObject`]
52    pub fn SDL_LoadObject(sofile: *const ::core::ffi::c_char) -> *mut SDL_SharedObject;
53}
54
55unsafe extern "C" {
56    /// Look up the address of the named function in a shared object.
57    ///
58    /// This function pointer is no longer valid after calling [`SDL_UnloadObject()`].
59    ///
60    /// This function can only look up C function names. Other languages may have
61    /// name mangling and intrinsic language support that varies from compiler to
62    /// compiler.
63    ///
64    /// Make sure you declare your function pointers with the same calling
65    /// convention as the actual library function. Your code will crash
66    /// mysteriously if you do not do this.
67    ///
68    /// If the requested function doesn't exist, NULL is returned.
69    ///
70    /// ## Parameters
71    /// - `handle`: a valid shared object handle returned by [`SDL_LoadObject()`].
72    /// - `name`: the name of the function to look up.
73    ///
74    /// ## Return value
75    /// Returns a pointer to the function or NULL on failure; call [`SDL_GetError()`]
76    ///   for more information.
77    ///
78    /// ## Thread safety
79    /// It is safe to call this function from any thread.
80    ///
81    /// ## Availability
82    /// This function is available since SDL 3.2.0.
83    ///
84    /// ## See also
85    /// - [`SDL_LoadObject`]
86    pub fn SDL_LoadFunction(
87        handle: *mut SDL_SharedObject,
88        name: *const ::core::ffi::c_char,
89    ) -> SDL_FunctionPointer;
90}
91
92unsafe extern "C" {
93    /// Unload a shared object from memory.
94    ///
95    /// Note that any pointers from this object looked up through
96    /// [`SDL_LoadFunction()`] will no longer be valid.
97    ///
98    /// ## Parameters
99    /// - `handle`: a valid shared object handle returned by [`SDL_LoadObject()`].
100    ///
101    /// ## Thread safety
102    /// It is safe to call this function from any thread.
103    ///
104    /// ## Availability
105    /// This function is available since SDL 3.2.0.
106    ///
107    /// ## See also
108    /// - [`SDL_LoadObject`]
109    pub fn SDL_UnloadObject(handle: *mut SDL_SharedObject);
110}
111
112/// An opaque datatype that represents a loaded shared object.
113///
114/// ## Availability
115/// This datatype is available since SDL 3.2.0.
116///
117/// ## See also
118/// - [`SDL_LoadObject`]
119/// - [`SDL_LoadFunction`]
120/// - [`SDL_UnloadObject`]
121#[repr(C)]
122pub struct SDL_SharedObject {
123    _opaque: [::core::primitive::u8; 0],
124}
125
126#[cfg(doc)]
127use crate::everything::*;
sdl3_sys/generated/loadso.rs

sdl3_sys/generated/
loadso.rs
