dynload -- encapsulates dynamic loading mechanisms and gives access to
functions in foreign dynamic libraries and code modules.
dlLoadLibrary(const char * libpath);
dlFreeLibrary(DLLib * pLib);
dlFindSymbol(DLLib * pLib, const char * pSymbolName);
dlGetLibraryPath(DLLib * pLib, char * sOut, int bufSize);
dlSymsInit(const char * libPath);
dlSymsCleanup(DLSyms * pSyms);
dlSymsCount(DLSyms * pSyms);
dlSymsName(DLSyms * pSyms, int index);
dlSymsNameFromValue(DLSyms * pSyms, void * value);
The dynload library provides an interface to load foreign dynamic
libraries and access to their symbols.
dlLoadLibrary() loads a dynamic library at libpath and returns a handle
to it for use in dlFreeLibrary() and dlFindSymbol() calls. Passing a null
pointer for the libpath argument is valid, and returns a handle to the
main executable of the calling code. Also, searching libraries in library
paths (e.g. by just passing the library's leaf name) should work, how-
ever, they are OS specific. Returns a null pointer on error.
dlFreeLibrary() frees the loaded library with handle pLib.
dlFindSymbol() returns a pointer to a symbol with name pSymbolName in the
library with handle pLib, or returns a null pointer if the symbol cannot
be found. The name is specified as it would appear in C source code (man-
gled if C++, etc.).
dlGetLibraryPath() can be used to get a copy of the path to the library
loaded with handle pLib. The parameter sOut is a pointer to a buffer of
size bufSize (in bytes), to hold the output string. The return value is
the size of the buffer (in bytes) needed to hold the null-terminated
string, or 0 if it can't be looked up. If bufSize >= return value > 1, a
null-terminted string with the path to the library should be in sOut. If
it returns 0, the library name wasn't able to be found. Please note that
this might happen in some rare cases, so make sure to always check.
The dlSyms* functions can be used to iterate over symbols. Since they can
be used on libraries that are not linked, they are made for symbol name
lookups, not to get symbols' addresses. For that refer to dlFindSymbol().
dlSymsInit() will return a handle (or null pointer on error) to the
shared object specified by libPath, to be used with the other dlSyms*
functions. Note that contrary to loading and linking libraries, no (OS-
specific) rules for searching libraries in library paths, etc. apply. The
handle must be freed with dlSymsCleanup(). dlSymsCount() returns the
number of symbols in the shared object, dlSymsName() and
dlSymsNameFromValue() are used to lookup symbol names using an index or
symbol's address, respectively, returning a null pointer on error. The
names are returned as they would appear in C source code (mangled if C++,
etc.). The address passed to dlSymsNameFromValue() must point to a loaded
dlGetLibraryPath() is not thread-safe on Darwin (macOS, iOS, ...) and
OpenBSD. dlSymsInit() is not thread-safe on Darwin. dlGetLibraryPath()
will not work on the following platforms when the library in question
doesn't have the (default) _init() and _fini() symbols exported (rare,
but possible): Haiku (all versions), OpenBSD < 3.7, NetBSD < 5.1, FreeBSD
The dynload library conforms to c99.
dyncall(3), dyncallback(3) and the dyncall manual (available in HTML and
PDF format) for more information.
Daniel Adler <firstname.lastname@example.org>
Tassilo Philipp <email@example.com>
May 6, 2018