dyncall library - C foreign function interface dyncall library: home - news - download - source/repository - bindings - documentation - license - credits - showcase/users - contact University of Göttingen 3ds Max, Maya Plugin Development - Potion Studios




     dynload – encapsulates dynamic loading mechanisms and gives access to
     functions in foreign dynamic libraries and code modules.


     #include <dynload.h>

     DLLib *
     dlLoadLibrary(const char * libpath);

     dlFreeLibrary(DLLib * pLib);

     void *
     dlFindSymbol(DLLib * pLib, const char * pSymbolName);

     dlGetLibraryPath(DLLib * pLib, char * sOut, int bufSize);

     dlSymsInit(const char * libPath);

     dlSymsCleanup(DLSyms * pSyms);

     dlSymsCount(DLSyms * pSyms);

     const char*
     dlSymsName(DLSyms * pSyms, int index);

     const char*
     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,
     however, they are OS specific. The libPath argument is expected to be
     UTF-8 encoded. 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
     (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
     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. 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

     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


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


     dlGetLibraryPath() is not thread-safe on Darwin (macOS, iOS, ...) and

     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 < 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


     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 ⟨dadler@uni-goettingen.de⟩
     Tassilo Philipp ⟨tphilipp@potion-studios.com⟩

                               December 6, 2022