NAME

AG_DSO — agar portable dynamic linker interface

SYNOPSIS

#include <agar/core.h>

DESCRIPTION

AG_DSO provides a cross-platform interface for loading code from a dynamic library file into the current process's address space, resolving symbols defined by the library, and unloading the library.

INTERFACE

AG_DSO *
AG_LoadDSO(const char *name, const char *path, Uint flags);

int
AG_SymDSO(AG_DSO *dso, const char *symbol, void **rv);

void
AG_LockDSO(void);

void
AG_UnlockDSO(void);

int
AG_UnloadDSO(AG_DSO *dso);

AG_DSO *
AG_LookupDSO(const char *name);

The AG_LoadDSO() function loads the dynamic library file at path into the current process's address space. If the library has already been loaded, the existing AG_DSO structure is returned and its reference count incremented. name is a string identifier for the library for use by the AG_Object(3) system independently of the file location. If the library was loaded successfully, a pointer to the new AG_DSO structure is returned. If an error has occurred return NULL with an error message.

The AG_SymDSO() function tries to resolve the named symbol. If successful, the value is returned into rv and 0 is returned. Otherwise, -1 is returned and an error message is set. Under threads, the value returned into rv remains valid as long as AG_LockDSO() is in effect. AG_SymDSO() automatically prepends an underscore to the symbol if required.

AG_LockDSO() and AG_UnlockDSO() acquire and release the lock protecting the list of loaded libraries and their resolved symbols. In multithreaded applications requiring the ability to unload modules, it is not safe to reference resolved symbols without acquiring this lock.

The AG_UnloadDSO() function decrements the reference count of the specified AG_DSO object. If it reaches zero, the library is removed from the process's address space.

AG_LookupDSO() searches the list of currently loaded DSOs by the specified name. If no match is found, NULL is returned.

STRUCTURE DATA

For the AG_DSO structure:

char name[AG_DSO_NAME_MAX]

Platform-independent name for this module.

char path[AG_PATHNAME_MAX]

Full path to dynamic library file.

TAILQ(AG_DSOSym) syms

List of previously resolved symbols

For the AG_DSOSym structure:

char *sym

Symbol name

char *p

Resolved address

EXAMPLES

The following code fragments loads a DSO and resolves a symbol from it:

AG_DSO *dso;
void *pMySymbol;

if ((dso = AG_LoadDSO("my_dso", 0)) == NULL) {
	AG_FatalError();
}
if (AG_SymDSO(dso, "my_symbol", &pMySymbol) == 0) {
	Verbose("Resolved \"my_symbol\" address: %p\n",
	    pMySymbol);
} else {
	Verbose("Could not resolve \"my_symbol\"\n");
}
AG_UnloadDSO(dso);

SEE ALSO

AG_DataSource(3), AG_Intro(3)

HISTORY

The AG_DSO interface first appeared in Agar 1.3.3.