SDL 3.0
SDL_loadso.h File Reference
+ Include dependency graph for SDL_loadso.h:
+ This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs

typedef struct SDL_SharedObject SDL_SharedObject
 

Functions

SDL_SharedObjectSDL_LoadObject (const char *sofile)
 
SDL_FunctionPointer SDL_LoadFunction (SDL_SharedObject *handle, const char *name)
 
void SDL_UnloadObject (SDL_SharedObject *handle)
 

Typedef Documentation

◆ SDL_SharedObject

CategorySharedObject

System-dependent library loading routines.

Shared objects are code that is programmatically loadable at runtime. Windows calls these "DLLs", Linux calls them "shared libraries", etc.

To use them, build such a library, then call SDL_LoadObject() on it. Once loaded, you can use SDL_LoadFunction() on that object to find the address of its exported symbols. When done with the object, call SDL_UnloadObject() to dispose of it.

Some things to keep in mind:

  • These functions only work on C function names. Other languages may have name mangling and intrinsic language support that varies from compiler to compiler.
  • Make sure you declare your function pointers with the same calling convention as the actual library function. Your code will crash mysteriously if you do not do this.
  • Avoid namespace collisions. If you load a symbol from the library, it is not defined whether or not it goes into the global symbol namespace for the application. If it does and it conflicts with symbols in your code or other shared libraries, you will not get the results you expect. :)
  • Once a library is unloaded, all pointers into it obtained through SDL_LoadFunction() become invalid, even if the library is later reloaded. Don't unload a library if you plan to use these pointers in the future. Notably: beware of giving one of these pointers to atexit(), since it may call that pointer after the library unloads. An opaque datatype that represents a loaded shared object.
Since
This datatype is available since SDL 3.1.3.
See also
SDL_LoadObject
SDL_LoadFunction
SDL_UnloadObject

Definition at line 77 of file SDL_loadso.h.

Function Documentation

◆ SDL_LoadFunction()

SDL_FunctionPointer SDL_LoadFunction ( SDL_SharedObject handle,
const char *  name 
)
extern

Look up the address of the named function in a shared object.

This function pointer is no longer valid after calling SDL_UnloadObject().

This function can only look up C function names. Other languages may have name mangling and intrinsic language support that varies from compiler to compiler.

Make sure you declare your function pointers with the same calling convention as the actual library function. Your code will crash mysteriously if you do not do this.

If the requested function doesn't exist, NULL is returned.

Parameters
handlea valid shared object handle returned by SDL_LoadObject().
namethe name of the function to look up.
Returns
a pointer to the function or NULL on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.1.3.
See also
SDL_LoadObject

◆ SDL_LoadObject()

SDL_SharedObject * SDL_LoadObject ( const char *  sofile)
extern

Dynamically load a shared object.

Parameters
sofilea system-dependent name of the object file.
Returns
an opaque pointer to the object handle or NULL on failure; call SDL_GetError() for more information.

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.1.3.
See also
SDL_LoadFunction
SDL_UnloadObject

◆ SDL_UnloadObject()

void SDL_UnloadObject ( SDL_SharedObject handle)
extern

Unload a shared object from memory.

Note that any pointers from this object looked up through SDL_LoadFunction() will no longer be valid.

Parameters
handlea valid shared object handle returned by SDL_LoadObject().

\threadsafety It is safe to call this function from any thread.

Since
This function is available since SDL 3.1.3.
See also
SDL_LoadObject