libdyn - Liquid War 6
Description: Liquid War 6

Next: libgen, Previous: libdsp, Up: C API

### 5.17 libdyn

#### 5.17.1 Overview

View lcov test coverage results on http://www.ufoot.org/liquidwar/v6/doc/coverage/src/lib/dyn/index.html.

#### 5.17.2 API

— Function: lw6dyn_dl_handle_t * lw6dyn_dlopen_backend_so (const char * so_file)

> Opens a .so file directly, using a valid (full) path name.

> Return value: a handle to the module, once it's opened. You might still need to call a module specific `init` function, but it's another story.

— Function: lw6dyn_dl_handle_t * lw6dyn_dlopen_shared_so (const char * so_file)

> Opens a .so file directly, using a valid (full) path name.

> Return value: a handle to the shared code, once it's opened. You might still need to call a module specific `init` function, but it's another story.

— Function: lw6dyn_dl_handle_t * lw6dyn_dlopen_backend (int argc, const char * [] argv, const char * top_level_lib, const char * backend_name)

> argc: the number of command-line arguments as passed to `main`

> top_level_lib: the top-level library concerned, this means is it "cli", "gfx", "snd" or "srv". This will tell the function to search for the .so file in the correct subdirectory. Think of this as a category.

> Opens a .so file corresponding to the given backend, it is capable to search for system libraries installed after "make install" but if not found, it will also search in the current build directory, finding the .so files in hidden .libs subdirectories.

> Return value: a handle to the module, once it's opened. You might still need to call a module specific `init` function, but it's another story.

— Function: lw6dyn_dl_handle_t * lw6dyn_dlopen_shared (int argc, const char * [] argv, const char * top_level_lib, const char * shared_name)

> argc: the number of command-line arguments as passed to `main`

> top_level_lib: the top-level library concerned, this means is it "cli", "gfx", "snd" or "srv". This will tell the function to search for the .so file in the correct subdirectory. Think of this as a category.

> Opens a .so file corresponding to the given shared code, it is capable to search for system libraries installed after "make install" but if not found, it will also search in the current build directory, finding the .so files in hidden .libs subdirectories.

> Return value: a handle to the shared code, once it's opened. This is different from a real module, there's no real prototype, it just loads code.

— Function: int lw6dyn_dlclose_backend (lw6dyn_dl_handle_t * handle)

> handle: the backend to close.

> Closes an opened backend. Note that you must call any backend specific clear, destroy, deinit, exit, function before.

> Return value: 1 if success, 0 on error.

— Function: int lw6dyn_dlclose_shared (lw6dyn_dl_handle_t * handle)

> handle: the shared code library to close.

> Closes an opened shared code library. Note that you must call any shared code library specific clear, destroy, deinit, exit, function before.

> Return value: 1 if success, 0 on error.

— Function: void * lw6dyn_dlsym (lw6dyn_dl_handle_t * handle, const char * func_name)

> handle: the backend concerned

> func_name: the function name, as a NULL terminated string

> Finds a C function in the given backend.

> Return value: a pointer to the function, NULL if not found.

— Function: lw6sys_assoc_t * lw6dyn_list_backends (int argc, const char * [] argv, const char * top_level_lib)

> argc: the number of command line args, as passed to main

> argv: the commind line args, as passed to main

> top_level_lib: the library category to query (gfx, snd, cli, srv ...)

> Returns an assoc which lists all the available modules. The key of the assoc entries in the module internal name such as 'gl' and the value associated is a NULL terminated string describing the module, for instance 'OpenGL'.

> Return value: an assoc object containing key/label pairs.

— Function: char * lw6dyn_path_find_backend (int argc, const char * [] argv, const char * top_level_lib, const char * backend_name)

> argc: the number of command-line arguments as passed to `main`

> top_level_lib: the top-level library concerned, this means is it "cli", "gfx", "snd" or "srv". This will tell the function to search for the .so file in the correct subdirectory. Think of this as a category.

> backend_name: the actual name of the backend, this is the name of the .so file, between "libmod_" and ".so". For instance, to find "libmod_gl.so", the right argument is "gl1".

> Get the full path to a .so file corresponding to the given backend, it is capable to search for system libraries installed after "make install" but if not found, it will also search in the current build directory, finding the .so files in hidden .libs subdirectories.

> Return value: the full path of the .so file, needs to be freed.

— Function: char * lw6dyn_path_find_shared (int argc, const char * [] argv, const char * top_level_lib, const char * shared_name)

> argc: the number of command-line arguments as passed to `main`

> top_level_lib: the top-level library concerned, this means is it "cli", "gfx", "snd" or "srv". This will tell the function to search for the .so file in the correct subdirectory. Think of this as a category.

> shared_name: the actual name of the shared code, this is the name of the .so file, between "libshared_" and ".so". For instance, to find "libshared_sdl.so", the right argument is "sdl".

> Get the full path to a .so file corresponding to the given shared code entry, it is capable to search for system libraries installed after "make install" but if not found, it will also search in the current build directory, finding the .so files in hidden .libs subdirectories. This is different from the standard module loader, since it will search for .so files with a slightly different name. The idea is to distinguish modules that are truely loadable and shared code that can't be used standalone and can't either be stuffed in the main binary since it refers to external dynamic library which will only be loaded at runtime.

> Return value: the full path of the .so file, needs to be freed.

— Function: int lw6dyn_test_register (int mode)

> mode: test mode (bitmask)

> Registers all tests for the libdyn module.

> Return value: 1 if test is successfull, 0 on error.

— Function: int lw6dyn_test_run (int mode)

> mode: test mode (bitmask)

> Runs the `dyn` module test suite, testing most (if not all...) functions.

> Return value: 1 if test is successfull, 0 on error.

— Struct: lw6dyn_dl_handle_s

> Handle on dynamic library. Well, actually, ltdl does already provide something like, so why use our own wrapper? It happens storing the library path, that's to say what .so files it comes from, is usefull for debugging, so this structure bundles those two informations together.

— Member of lw6dyn_dl_handle_s: handle

> Type: `lt_dlhandle`

> Definition: `lt_dlhandle lw6dyn_dl_handle_s::handle`

> Libtool handler.

— Member of lw6dyn_dl_handle_s: library_path

> Type: `char *`

> Definition: `char* lw6dyn_dl_handle_s::library_path`

> Path to .so file containing the code, or whatever file is relevant on the current platform, the idea is to keep track of where the library comes from.

— Member of lw6dyn_dl_handle_s: is_backend

> Type: `int`

> Definition: `int lw6dyn_dl_handle_s::is_backend`

> True (1) if the handle is a backend or false (0) if it's just some shared code.

— Member of lw6dyn_dl_handle_s: is_dlclose_safe

> Type: `int`

> Definition: `int lw6dyn_dl_handle_s::is_dlclose_safe`

> True (1) if one can safely call dlclose on this backend. Set to false (0) if low level dlclose must be skipped. For some reason, some (external) libraries really do not behave well when unloaded on the fly, even if we stop threads using them and don't use them anymore. The workarround is to have this flag defined, to skip the internal close to dlclose. LW will still free the memory, but won't call libtool dlclose for real. Libtool keeps track of this internally and won't reload it on next call, maintain reference counts etc. so there's no real harm. Except it just looks ugly not to be able to truely unload the module.