|
1
|
1 /*
|
|
|
2 Simple DirectMedia Layer
|
|
|
3 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
|
|
|
4
|
|
|
5 This software is provided 'as-is', without any express or implied
|
|
|
6 warranty. In no event will the authors be held liable for any damages
|
|
|
7 arising from the use of this software.
|
|
|
8
|
|
|
9 Permission is granted to anyone to use this software for any purpose,
|
|
|
10 including commercial applications, and to alter it and redistribute it
|
|
|
11 freely, subject to the following restrictions:
|
|
|
12
|
|
|
13 1. The origin of this software must not be misrepresented; you must not
|
|
|
14 claim that you wrote the original software. If you use this software
|
|
|
15 in a product, an acknowledgment in the product documentation would be
|
|
|
16 appreciated but is not required.
|
|
|
17 2. Altered source versions must be plainly marked as such, and must not be
|
|
|
18 misrepresented as being the original software.
|
|
|
19 3. This notice may not be removed or altered from any source distribution.
|
|
|
20 */
|
|
|
21
|
|
|
22 /* WIKI CATEGORY: SharedObject */
|
|
|
23
|
|
|
24 /**
|
|
|
25 * # CategorySharedObject
|
|
|
26 *
|
|
|
27 * System-dependent library loading routines.
|
|
|
28 *
|
|
|
29 * Shared objects are code that is programmatically loadable at runtime.
|
|
|
30 * Windows calls these "DLLs", Linux calls them "shared libraries", etc.
|
|
|
31 *
|
|
|
32 * To use them, build such a library, then call SDL_LoadObject() on it. Once
|
|
|
33 * loaded, you can use SDL_LoadFunction() on that object to find the address
|
|
|
34 * of its exported symbols. When done with the object, call SDL_UnloadObject()
|
|
|
35 * to dispose of it.
|
|
|
36 *
|
|
|
37 * Some things to keep in mind:
|
|
|
38 *
|
|
|
39 * - These functions only work on C function names. Other languages may have
|
|
|
40 * name mangling and intrinsic language support that varies from compiler to
|
|
|
41 * compiler.
|
|
|
42 * - Make sure you declare your function pointers with the same calling
|
|
|
43 * convention as the actual library function. Your code will crash
|
|
|
44 * mysteriously if you do not do this.
|
|
|
45 * - Avoid namespace collisions. If you load a symbol from the library, it is
|
|
|
46 * not defined whether or not it goes into the global symbol namespace for
|
|
|
47 * the application. If it does and it conflicts with symbols in your code or
|
|
|
48 * other shared libraries, you will not get the results you expect. :)
|
|
|
49 * - Once a library is unloaded, all pointers into it obtained through
|
|
|
50 * SDL_LoadFunction() become invalid, even if the library is later reloaded.
|
|
|
51 * Don't unload a library if you plan to use these pointers in the future.
|
|
|
52 * Notably: beware of giving one of these pointers to atexit(), since it may
|
|
|
53 * call that pointer after the library unloads.
|
|
|
54 */
|
|
|
55
|
|
|
56 #ifndef SDL_loadso_h_
|
|
|
57 #define SDL_loadso_h_
|
|
|
58
|
|
|
59 #include <SDL3/SDL_stdinc.h>
|
|
|
60 #include <SDL3/SDL_error.h>
|
|
|
61
|
|
|
62 #include <SDL3/SDL_begin_code.h>
|
|
|
63 /* Set up for C function definitions, even when using C++ */
|
|
|
64 #ifdef __cplusplus
|
|
|
65 extern "C" {
|
|
|
66 #endif
|
|
|
67
|
|
|
68 /**
|
|
|
69 * An opaque datatype that represents a loaded shared object.
|
|
|
70 *
|
|
|
71 * \since This datatype is available since SDL 3.2.0.
|
|
|
72 *
|
|
|
73 * \sa SDL_LoadObject
|
|
|
74 * \sa SDL_LoadFunction
|
|
|
75 * \sa SDL_UnloadObject
|
|
|
76 */
|
|
|
77 typedef struct SDL_SharedObject SDL_SharedObject;
|
|
|
78
|
|
|
79 /**
|
|
|
80 * Dynamically load a shared object.
|
|
|
81 *
|
|
|
82 * \param sofile a system-dependent name of the object file.
|
|
|
83 * \returns an opaque pointer to the object handle or NULL on failure; call
|
|
|
84 * SDL_GetError() for more information.
|
|
|
85 *
|
|
|
86 * \threadsafety It is safe to call this function from any thread.
|
|
|
87 *
|
|
|
88 * \since This function is available since SDL 3.2.0.
|
|
|
89 *
|
|
|
90 * \sa SDL_LoadFunction
|
|
|
91 * \sa SDL_UnloadObject
|
|
|
92 */
|
|
|
93 extern SDL_DECLSPEC SDL_SharedObject * SDLCALL SDL_LoadObject(const char *sofile);
|
|
|
94
|
|
|
95 /**
|
|
|
96 * Look up the address of the named function in a shared object.
|
|
|
97 *
|
|
|
98 * This function pointer is no longer valid after calling SDL_UnloadObject().
|
|
|
99 *
|
|
|
100 * This function can only look up C function names. Other languages may have
|
|
|
101 * name mangling and intrinsic language support that varies from compiler to
|
|
|
102 * compiler.
|
|
|
103 *
|
|
|
104 * Make sure you declare your function pointers with the same calling
|
|
|
105 * convention as the actual library function. Your code will crash
|
|
|
106 * mysteriously if you do not do this.
|
|
|
107 *
|
|
|
108 * If the requested function doesn't exist, NULL is returned.
|
|
|
109 *
|
|
|
110 * \param handle a valid shared object handle returned by SDL_LoadObject().
|
|
|
111 * \param name the name of the function to look up.
|
|
|
112 * \returns a pointer to the function or NULL on failure; call SDL_GetError()
|
|
|
113 * for more information.
|
|
|
114 *
|
|
|
115 * \threadsafety It is safe to call this function from any thread.
|
|
|
116 *
|
|
|
117 * \since This function is available since SDL 3.2.0.
|
|
|
118 *
|
|
|
119 * \sa SDL_LoadObject
|
|
|
120 */
|
|
|
121 extern SDL_DECLSPEC SDL_FunctionPointer SDLCALL SDL_LoadFunction(SDL_SharedObject *handle, const char *name);
|
|
|
122
|
|
|
123 /**
|
|
|
124 * Unload a shared object from memory.
|
|
|
125 *
|
|
|
126 * Note that any pointers from this object looked up through
|
|
|
127 * SDL_LoadFunction() will no longer be valid.
|
|
|
128 *
|
|
|
129 * \param handle a valid shared object handle returned by SDL_LoadObject().
|
|
|
130 *
|
|
|
131 * \threadsafety It is safe to call this function from any thread.
|
|
|
132 *
|
|
|
133 * \since This function is available since SDL 3.2.0.
|
|
|
134 *
|
|
|
135 * \sa SDL_LoadObject
|
|
|
136 */
|
|
|
137 extern SDL_DECLSPEC void SDLCALL SDL_UnloadObject(SDL_SharedObject *handle);
|
|
|
138
|
|
|
139 /* Ends C function definitions when using C++ */
|
|
|
140 #ifdef __cplusplus
|
|
|
141 }
|
|
|
142 #endif
|
|
|
143 #include <SDL3/SDL_close_code.h>
|
|
|
144
|
|
|
145 #endif /* SDL_loadso_h_ */
|
