|
0
|
1 %//////////////////////////////////////////////////////////////////////////////
|
|
|
2 %
|
|
228
|
3 % Copyright (c) 2007-2017 Daniel Adler <dadler@uni-goettingen.de>,
|
|
0
|
4 % Tassilo Philipp <tphilipp@potion-studios.com>
|
|
|
5 %
|
|
|
6 % Permission to use, copy, modify, and distribute this software for any
|
|
|
7 % purpose with or without fee is hereby granted, provided that the above
|
|
|
8 % copyright notice and this permission notice appear in all copies.
|
|
|
9 %
|
|
|
10 % THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
|
|
11 % WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
|
|
12 % MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
|
|
13 % ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
|
|
14 % WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
|
|
15 % ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
|
|
16 % OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
|
|
17 %
|
|
|
18 %//////////////////////////////////////////////////////////////////////////////
|
|
|
19
|
|
|
20 \section{\product{Dynload} C library API}
|
|
|
21
|
|
490
|
22 See the dynload(3) manpage for more information.
|
|
228
|
23
|
|
490
|
24 %@@@ removed, as manpages are more precise and up to date ------------------->
|
|
|
25 %
|
|
|
26 %The \product{dynload} library encapsulates dynamic loading mechanisms and
|
|
|
27 %gives access to functions in foreign dynamic libraries and code modules.
|
|
|
28 %
|
|
|
29 %\subsection{Loading code}
|
|
|
30 %
|
|
|
31 %\begin{lstlisting}[language=c,label=dl-load]
|
|
|
32 %DLLib* dlLoadLibrary(const char* libpath);
|
|
|
33 %void dlFreeLibrary(void* libhandle);
|
|
|
34 %\end{lstlisting}
|
|
|
35 %
|
|
|
36 %\lstinline{dlLoadLibrary} loads a dynamic library at \lstinline{libpath}
|
|
|
37 %and returns a handle to it for use in \lstinline{dlFreeLibrary} and
|
|
|
38 %\lstinline{dlFindSymbol} calls. Passing a null pointer for the \lstinline{libpath}
|
|
|
39 %argument is valid, and returns a handle to the main executable of the calling code.
|
|
|
40 %Also, searching libraries in library paths (e.g. by just passing the library's leaf
|
|
|
41 %name) should work, however, they are OS specific. Returns a null pointer on error.
|
|
|
42 %
|
|
|
43 %\lstinline{dlFreeLibrary} frees the loaded library with handle \lstinline{pLib}.
|
|
|
44 %
|
|
|
45 %\subsection{Retrieving functions}
|
|
|
46 %
|
|
|
47 %\begin{lstlisting}[language=c]
|
|
|
48 %void* dlFindSymbol(void* libhandle, const char* symbol);
|
|
|
49 %\end{lstlisting}
|
|
|
50 %
|
|
|
51 %This function returns a pointer to a symbol with name \lstinline{pSymbolName} in the
|
|
|
52 %library with handle \lstinline{pLib}, or returns a null pointer if the symbol cannot
|
|
|
53 %be found. The name is specified as it would appear in C source code (mangled if C++, etc.).
|
|
|
54 %
|
|
|
55 %\subsection{Misc functions}
|
|
|
56 %\begin{lstlisting}[language=c]
|
|
|
57 %int dlGetLibraryPath(DLLib* pLib, char* sOut, int bufSize);
|
|
|
58 %\end{lstlisting}
|
|
|
59 %
|
|
|
60 %This function can be used to get a copy of the path to the library loaded with handle
|
|
|
61 %\lstinline{pLib}. The parameter \lstinline{sOut} is a pointer to a buffer of size
|
|
|
62 %\lstinline{bufSize} (in bytes), to hold the output string. The return value is the size
|
|
|
63 %of the buffer (in bytes) needed to hold the null-terminated string, or 0 if it can't be
|
|
|
64 %looked up. If \lstinline{bufSize} \textgreater= return value \textgreater 1, a null-terminted string with the
|
|
|
65 %path to the library should be in \lstinline{sOut}. If it returns 0, the library name wasn't
|
|
|
66 %able to be found. Please note that this might happen in some rare cases, so make sure to always check.
|
|
|
67 %
|
|
|
68 %\subsection{Symbol iteration}
|
|
|
69 %
|
|
|
70 %\begin{lstlisting}[language=c]
|
|
|
71 %DLSyms* dlSymsInit(const char* libPath);
|
|
|
72 %void dlSymsCleanup(DLSyms* pSyms);
|
|
|
73 %int dlSymsCount(DLSyms* pSyms);
|
|
|
74 %const char* dlSymsName(DLSyms* pSyms, int index);
|
|
|
75 %const char* dlSymsNameFromValue(DLSyms* pSyms, void* value); /* symbol must be loaded */
|
|
|
76 %\end{lstlisting}
|
|
|
77 %
|
|
|
78 %
|
|
|
79 %These functions can be used to iterate over symbols. Since they can be used on libraries that are not linked, they are made
|
|
|
80 %for symbol name lookups, not to get a symbol's address. For that refer to
|
|
|
81 %\lstinline{dlFindSymbol}. \lstinline{dlSymsInit} will return a handle (or a null pointer
|
|
|
82 %on error) to the shared object specified by \lstinline{libPath}, to be used with the other dlSyms* functions. Note that contrary
|
|
|
83 %to loading and linking libraries, no (OS-specific) rules for searching libraries in library paths, etc. apply. The handle must be freed with
|
|
|
84 %\lstinline{dlSymsCleanup}. \lstinline{dlSymsCount} returns the number of
|
|
|
85 %symbols in the shared object, \lstinline{dlSymsName} and \lstinline{dlSymsNameFromValue}
|
|
|
86 %are used to lookup symbol names using an index or symbol's address, respectively,
|
|
|
87 %returning a null pointer on error. The names are returned as they would appear
|
|
|
88 %in C source code (mangled if C++, etc.). The address passed to \lstinline{dlSymsNameFromValue}
|
|
|
89 %must point to a loaded symbol.
|
|
|
90 %
|
