MODULE: runtime loading of shared libraries

Macros
#define	N_MODULE_ERROR_MAX   512
	longest error text kept by n_module_error(), terminator included

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

Detailed Description

Macro Definition Documentation

N_MODULE_ERROR_MAX

#define N_MODULE_ERROR_MAX   512

longest error text kept by n_module_error(), terminator included

Definition at line 58 of file n_module.h.

Referenced by _n_module_set_error().

Function Documentation

n_module_close()

int n_module_close

(

N_MODULE **

module

)

Close a library and free its handle.

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

Parameters

module

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

Returns

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

Definition at line 136 of file n_module.c.

References _n_module_set_error(), and Free.

Referenced by _a4_midi_shutdown(), and main().

Here is the call graph for this function:

Here is the caller graph for this function:

n_module_error()

const char * n_module_error

(

void

)

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

Returns

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

Definition at line 157 of file n_module.c.

References _n_module_last_error.

Referenced by main().

Here is the caller graph for this function:

n_module_extension()

const char * n_module_extension

(

void

)

The file extension shared libraries have on this platform.

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

Returns

a static string, never NULL.

Definition at line 161 of file n_module.c.

Referenced by main().

Here is the caller graph for this function:

n_module_open()

N_MODULE * n_module_open

(

const char *

path

)

Open a shared library.

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.

Parameters

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

Returns

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()).

Definition at line 68 of file n_module.c.

References __n_assert, _n_module_last_error, _n_module_set_error(), and Malloc.

Referenced by _a4_fluidsynth_open().

Here is the call graph for this function:

Here is the caller graph for this function:

n_module_symbol()

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

Find a symbol in an opened library.

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.

Parameters

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

Returns

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

Definition at line 110 of file n_module.c.

References __n_assert, _n_module_last_error, _n_module_set_error(), and N_MODULE::handle.

Referenced by _a4_fluidsynth_sym(), and main().

Here is the call graph for this function:

Here is the caller graph for this function: