Mercurial > pub > dyncall > dyncall
view doc/manual/manual_dynload_api.tex @ 237:98503af08916
- changelog mentioning darwin/ppc fixes
author | Tassilo Philipp |
---|---|
date | Tue, 02 May 2017 02:55:16 +0200 |
parents | f8a6e60598cc |
children | 2a77747a5496 |
line wrap: on
line source
%////////////////////////////////////////////////////////////////////////////// % % Copyright (c) 2007-2017 Daniel Adler <dadler@uni-goettingen.de>, % Tassilo Philipp <tphilipp@potion-studios.com> % % Permission to use, copy, modify, and distribute this software for any % purpose with or without fee is hereby granted, provided that the above % copyright notice and this permission notice appear in all copies. % % THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES % WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF % MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR % ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES % WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN % ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF % OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. % %////////////////////////////////////////////////////////////////////////////// \newpage \section{\product{Dynload} C library API} The \product{dynload} library encapsulates dynamic loading mechanisms and gives access to functions in foreign dynamic libraries and code modules. \subsection{Loading code} \begin{lstlisting}[language=c,label=dl-load] DLLib* dlLoadLibrary(const char* libpath); void dlFreeLibrary(void* libhandle); \end{lstlisting} \lstinline{dlLoadLibrary} loads a dynamic library at \lstinline{libpath} and returns a handle to it for use in \lstinline{dlFreeLibrary} and \lstinline{dlFindSymbol} calls. \lstinline{dlFreeLibrary} frees the loaded library with handle \lstinline{pLib}. \subsection{Retrieving functions} \begin{lstlisting}[language=c] void* dlFindSymbol(void* libhandle, const char* symbol); \end{lstlisting} This function returns a pointer to a symbol with name \lstinline{pSymbolName} in the library with handle \lstinline{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.). \subsection{Symbol iteration} \begin{lstlisting}[language=c] 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); /* symbol must be loaded */ \end{lstlisting} These functions can be used to iterate over symbols. Note that they are made for symbol name lookups, not to get a symbol's address. For that refer to \lstinline{dlFindSymbol}. \lstinline{dlSymsInit} will return a handle (or a null pointer on error) to the shared object specified by \lstinline{libPath}. The returned handle is to be used with the other functions. The handle must be freed with \lstinline{dlSymsCleanup}. \lstinline{dlSymsCount} returns the number of symbols in the shared object, \lstinline{dlSymsName} and \lstinline{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 \lstinline{dlSymsNameFromValue} must point to a loaded symbol.