5 Module N_MODULE
gullradriel edited this page 2026-10-09 00:55:18 +02:00

MODULE: runtime loading of shared libraries

Functions

Name
void * n_module_symbol(N_MODULE * module, const char * name)
Find a symbol in an opened library.
N_MODULE * n_module_open(const char * path)
Open a shared library.
const char * n_module_extension(void )
The file extension shared libraries have on this platform.
const char * n_module_error(void )
What the system said about this thread's last failed call.
int n_module_close(N_MODULE ** module)
Close a library and free its handle.

Defines

Name
N_MODULE_ERROR_MAX
longest error text kept by n_module_error(), terminator included

Functions Documentation

function n_module_symbol

void * n_module_symbol(
    N_MODULE * module,
    const char * name
)

Find a symbol in an opened library.

Parameters:

  • module library from n_module_open(). Must not be NULL.
  • name symbol name. Must not be NULL.

Return: the address, or NULL when the library has no such symbol (see n_module_error()). The address is valid until the module is closed.

The address of a function comes back as a void pointer, which C does not define a conversion from; copy it into a function pointer with memcpy, which is what every loader on both platforms relies on.

function n_module_open

N_MODULE * n_module_open(
    const char * path
)

Open a shared library.

Parameters:

  • path library file name or path. Must not be NULL.

Return: a new N_MODULE owned by the caller, to release with n_module_close(), or NULL when it cannot be opened (see n_module_error()).

path is handed to the system loader as it is: a bare file name is looked up the platform's way (LD_LIBRARY_PATH and the cache on Linux, the program's directory and PATH on Windows), a path with a directory is opened as given. On POSIX the library is opened RTLD_LAZY | RTLD_LOCAL, so its symbols do not leak into the ones the program already has. On Windows path is UTF-8.

function n_module_extension

const char * n_module_extension(
    void 
)

The file extension shared libraries have on this platform.

Return: a static string, never NULL.

What a plugin host looks for in a directory: ".dll" on Windows, ".dylib" on macOS, ".so" elsewhere.

function n_module_error

const char * n_module_error(
    void 
)

What the system said about this thread's last failed call.

Return: a string owned by this module, valid until this thread's next call into it; empty when nothing has failed. Never NULL.

function n_module_close

int n_module_close(
    N_MODULE ** module
)

Close a library and free its handle.

Parameters:

  • module address of the handle; set to NULL. NULL, or a pointer to NULL, is a no-op.

Return: TRUE, or FALSE when the system refused to close it (the handle is freed and set to NULL either way).

Every address found with n_module_symbol() is invalid afterwards: the system may unmap the library's code.

Macros Documentation

define N_MODULE_ERROR_MAX

#define N_MODULE_ERROR_MAX 512

longest error text kept by n_module_error(), terminator included