Note: The Agar manual pages follow certain conventions, notably
concerning function return values. Please read
AG_Intro(3)
first.
SYNOPSIS
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 occured, NULL is returned and an error message is set.
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
|
|
SEE ALSO
HISTORY
|
The
AG_DSO interface first appeared in
Agar 1.3.3.
|
