sdl3-bindgen-sys
Safe HaskellNone
LanguageGHC2021

SDL3.Sys.Loadso

Description

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 loadObject on it. Once loaded, you can use loadFunction on that object to find the address of its exported symbols. When done with the object, call 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 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.
See also
loadObject, loadFunction, unloadObject

FFI conventions

Unsuffixed aliases are unsafe foreign imports; aliases suffixed Safe are safe. Functions whose callbacks fire during the call export only the Safe alias (the genuine unsafe import stays reachable under SDL3.Sys.Bindgen.Loadso.Unsafe); functions curated unsafe-only export only the unsuffixed one. Each alias's documentation records its flavor and rationale.

Full conventions: SDL3.Sys.

Since: 3.2.0

Synopsis

Documentation

module SDL3.Sys.Bindgen.Loadso

Function aliases

loadObject Source #

Arguments

:: PtrConst CChar
sofile
a system-dependent name of the object file.
-> IO (Ptr SDL_SharedObject) 

Dynamically load a shared object.

Returns
an opaque pointer to the object handle or NULL on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
loadFunction, unloadObject

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_LoadObject. The safe flavor is loadObjectSafe .
C declaration
SDL_LoadObject, defined at SDL3/SDL_loadso.h 93:48

Since: 3.2.0

loadObjectSafe Source #

Arguments

:: PtrConst CChar
sofile
a system-dependent name of the object file.
-> IO (Ptr SDL_SharedObject) 

Dynamically load a shared object.

Returns
an opaque pointer to the object handle or NULL on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
loadFunction, unloadObject

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_LoadObject. The unsafe flavor is loadObject .
C declaration
SDL_LoadObject, defined at SDL3/SDL_loadso.h 93:48

Since: 3.2.0

loadFunction Source #

Arguments

:: Ptr SDL_SharedObject
handle
a valid shared object handle returned by loadObject.
-> PtrConst CChar
name
the name of the function to look up.
-> IO SDL_FunctionPointer 

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

This function pointer is no longer valid after calling 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.

Returns
a pointer to the function or NULL on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
loadObject

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_LoadFunction. The safe flavor is loadFunctionSafe .
C declaration
SDL_LoadFunction, defined at SDL3/SDL_loadso.h 121:49

Since: 3.2.0

loadFunctionSafe Source #

Arguments

:: Ptr SDL_SharedObject
handle
a valid shared object handle returned by loadObject.
-> PtrConst CChar
name
the name of the function to look up.
-> IO SDL_FunctionPointer 

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

This function pointer is no longer valid after calling 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.

Returns
a pointer to the function or NULL on failure; call getError for more information.
Thread safety
It is safe to call this function from any thread.
See also
loadObject

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_LoadFunction. The unsafe flavor is loadFunction .
C declaration
SDL_LoadFunction, defined at SDL3/SDL_loadso.h 121:49

Since: 3.2.0

unloadObject Source #

Arguments

:: Ptr SDL_SharedObject
handle
a valid shared object handle returned by loadObject.
-> IO () 

Unload a shared object from memory.

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

Thread safety
It is safe to call this function from any thread.
See also
loadObject

sdl3-bindgen-sys notes

Expand
FFI safety
Unsafe foreign import of SDL_UnloadObject. The safe flavor is unloadObjectSafe .
C declaration
SDL_UnloadObject, defined at SDL3/SDL_loadso.h 137:34

Since: 3.2.0

unloadObjectSafe Source #

Arguments

:: Ptr SDL_SharedObject
handle
a valid shared object handle returned by loadObject.
-> IO () 

Unload a shared object from memory.

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

Thread safety
It is safe to call this function from any thread.
See also
loadObject

sdl3-bindgen-sys notes

Expand
FFI safety
Safe foreign import of SDL_UnloadObject. The unsafe flavor is unloadObject .
C declaration
SDL_UnloadObject, defined at SDL3/SDL_loadso.h 137:34

Since: 3.2.0