%//////////////////////////////////////////////////////////////////////////////
%
% 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.