FreeBSD Manual Pages
NAME dynload -- encapsulates dynamic loading mechanisms and gives access to functions in foreign dynamic libraries and code modules. SYNOPSIS #include <dynload.h> DLLib * dlLoadLibrary(const char * libpath); void dlFreeLibrary(DLLib * pLib); void * dlFindSymbol(DLLib * pLib, const char * pSymbolName); int dlGetLibraryPath(DLLib * pLib, char * sOut, int bufSize); DLSyms* dlSymsInit(const char * libPath); void dlSymsCleanup(DLSyms * pSyms); int dlSymsCount(DLSyms * pSyms); const char* dlSymsName(DLSyms * pSyms, int index); const char* dlSymsNameFromValue(DLSyms * pSyms, void * value); DESCRIPTION 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, however, they are OS specific. The libPath argument is expected to be UTF-8 encoded. Re- turns 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 (mangled 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 (UTF-8 encoded). The re- turn 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. Passing a null pointer as pLib returns the path to the executable (not guaranteed to be absolute - if it isn't it's relative to the working directory the process was started in, not the current one). 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, re- turning a null pointer on error. The names are returned as they would ap- pear in C source code (mangled if C++, etc.). The address passed to dlSym- sNameFromValue() must point to a loaded symbol. NOTES dlLoadLibrary() does handle loading dylibs on macos >= 11.0.1 that aren't on the file system but are provided through the OS' "built-in dynamic linker cache of all system-provided libraries" (to load, use same "path" as one would with dlopen(3)). BUGS 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 li- brary 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 < 4.8 Getting the executable's path by passing NULL in pLib to dlGetLibraryPath() fails on the following platforms: Haiku (all versions), OpenBSD < 3.7, NetBSD < 5.1, FreeBSD < 4.8 CONFORMING TO The dynload library conforms to c99. SEE ALSO dyncall(3), dyncallback(3) and the dyncall manual (available in HTML and PDF format) for more information. AUTHORS Daniel Adler <dadler@uni-goettingen.de> Tassilo Philipp <tphilipp@potion-studios.com> $Mdocdate$ dynload(3)
NAME | SYNOPSIS | DESCRIPTION | NOTES | BUGS | CONFORMING TO | SEE ALSO | AUTHORS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=dynload&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>