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

\section{\product{Dynload} C library API}

See the dynload(3) manpage for more information.

%@@@ removed, as manpages are more precise and up to date ------------------->
%
%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. Passing a null pointer for the \lstinline{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. Returns a null pointer on error.
%
%\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{Misc functions}
%\begin{lstlisting}[language=c]
%int dlGetLibraryPath(DLLib* pLib, char* sOut, int bufSize);
%\end{lstlisting}
%
%This function can be used to get a copy of the path to the library loaded with handle
%\lstinline{pLib}. The parameter \lstinline{sOut} is a pointer to a buffer of size
%\lstinline{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 \lstinline{bufSize} \textgreater= return value \textgreater 1, a null-terminted string with the
%path to the library should be in \lstinline{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.
%
%\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. Since they can be used on libraries that are not linked, 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}, 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
%\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.
%