Mercurial > pub > dyncall > dyncall

comparison doc/manual/manual_dynload_api.tex @ 490:17287342e273

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
manual: - removed all API description and referred to manual instead, to avoid outdated and/or duplicated doc - cleanups and clarificaions
author Tassilo Philipp
date Sun, 20 Mar 2022 14:26:55 +0100
parents b47168dacba6
children
comparison
equal deleted inserted replaced
489:63f623bff0b9 490:17287342e273
15 % ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15 % ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
16 % OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16 % OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
17 % 17 %
18 %////////////////////////////////////////////////////////////////////////////// 18 %//////////////////////////////////////////////////////////////////////////////
19 19
20 \clearpage
21 \section{\product{Dynload} C library API} 20 \section{\product{Dynload} C library API}
22 21
23 The \product{dynload} library encapsulates dynamic loading mechanisms and 22 See the dynload(3) manpage for more information.
24 gives access to functions in foreign dynamic libraries and code modules.
25 23
26 \subsection{Loading code} 24 %@@@ removed, as manpages are more precise and up to date ------------------->
27 25 %
28 \begin{lstlisting}[language=c,label=dl-load] 26 %The \product{dynload} library encapsulates dynamic loading mechanisms and
29 DLLib* dlLoadLibrary(const char* libpath); 27 %gives access to functions in foreign dynamic libraries and code modules.
30 void dlFreeLibrary(void* libhandle); 28 %
31 \end{lstlisting} 29 %\subsection{Loading code}
32 30 %
33 \lstinline{dlLoadLibrary} loads a dynamic library at \lstinline{libpath} 31 %\begin{lstlisting}[language=c,label=dl-load]
34 and returns a handle to it for use in \lstinline{dlFreeLibrary} and 32 %DLLib* dlLoadLibrary(const char* libpath);
35 \lstinline{dlFindSymbol} calls. Passing a null pointer for the \lstinline{libpath} 33 %void dlFreeLibrary(void* libhandle);
36 argument is valid, and returns a handle to the main executable of the calling code. 34 %\end{lstlisting}
37 Also, searching libraries in library paths (e.g. by just passing the library's leaf 35 %
38 name) should work, however, they are OS specific. Returns a null pointer on error. 36 %\lstinline{dlLoadLibrary} loads a dynamic library at \lstinline{libpath}
39 37 %and returns a handle to it for use in \lstinline{dlFreeLibrary} and
40 \lstinline{dlFreeLibrary} frees the loaded library with handle \lstinline{pLib}. 38 %\lstinline{dlFindSymbol} calls. Passing a null pointer for the \lstinline{libpath}
41 39 %argument is valid, and returns a handle to the main executable of the calling code.
42 \subsection{Retrieving functions} 40 %Also, searching libraries in library paths (e.g. by just passing the library's leaf
43 41 %name) should work, however, they are OS specific. Returns a null pointer on error.
44 \begin{lstlisting}[language=c] 42 %
45 void* dlFindSymbol(void* libhandle, const char* symbol); 43 %\lstinline{dlFreeLibrary} frees the loaded library with handle \lstinline{pLib}.
46 \end{lstlisting} 44 %
47 45 %\subsection{Retrieving functions}
48 This function returns a pointer to a symbol with name \lstinline{pSymbolName} in the 46 %
49 library with handle \lstinline{pLib}, or returns a null pointer if the symbol cannot 47 %\begin{lstlisting}[language=c]
50 be found. The name is specified as it would appear in C source code (mangled if C++, etc.). 48 %void* dlFindSymbol(void* libhandle, const char* symbol);
51 49 %\end{lstlisting}
52 \subsection{Misc functions} 50 %
53 \begin{lstlisting}[language=c] 51 %This function returns a pointer to a symbol with name \lstinline{pSymbolName} in the
54 int dlGetLibraryPath(DLLib* pLib, char* sOut, int bufSize); 52 %library with handle \lstinline{pLib}, or returns a null pointer if the symbol cannot
55 \end{lstlisting} 53 %be found. The name is specified as it would appear in C source code (mangled if C++, etc.).
56 54 %
57 This function can be used to get a copy of the path to the library loaded with handle 55 %\subsection{Misc functions}
58 \lstinline{pLib}. The parameter \lstinline{sOut} is a pointer to a buffer of size 56 %\begin{lstlisting}[language=c]
59 \lstinline{bufSize} (in bytes), to hold the output string. The return value is the size 57 %int dlGetLibraryPath(DLLib* pLib, char* sOut, int bufSize);
60 of the buffer (in bytes) needed to hold the null-terminated string, or 0 if it can't be 58 %\end{lstlisting}
61 looked up. If \lstinline{bufSize} \textgreater= return value \textgreater 1, a null-terminted string with the 59 %
62 path to the library should be in \lstinline{sOut}. If it returns 0, the library name wasn't 60 %This function can be used to get a copy of the path to the library loaded with handle
63 able to be found. Please note that this might happen in some rare cases, so make sure to always check. 61 %\lstinline{pLib}. The parameter \lstinline{sOut} is a pointer to a buffer of size
64 62 %\lstinline{bufSize} (in bytes), to hold the output string. The return value is the size
65 \subsection{Symbol iteration} 63 %of the buffer (in bytes) needed to hold the null-terminated string, or 0 if it can't be
66 64 %looked up. If \lstinline{bufSize} \textgreater= return value \textgreater 1, a null-terminted string with the
67 \begin{lstlisting}[language=c] 65 %path to the library should be in \lstinline{sOut}. If it returns 0, the library name wasn't
68 DLSyms* dlSymsInit(const char* libPath); 66 %able to be found. Please note that this might happen in some rare cases, so make sure to always check.
69 void dlSymsCleanup(DLSyms* pSyms); 67 %
70 int dlSymsCount(DLSyms* pSyms); 68 %\subsection{Symbol iteration}
71 const char* dlSymsName(DLSyms* pSyms, int index); 69 %
72 const char* dlSymsNameFromValue(DLSyms* pSyms, void* value); /* symbol must be loaded */ 70 %\begin{lstlisting}[language=c]
73 \end{lstlisting} 71 %DLSyms* dlSymsInit(const char* libPath);
74 72 %void dlSymsCleanup(DLSyms* pSyms);
75 73 %int dlSymsCount(DLSyms* pSyms);
76 These functions can be used to iterate over symbols. Since they can be used on libraries that are not linked, they are made 74 %const char* dlSymsName(DLSyms* pSyms, int index);
77 for symbol name lookups, not to get a symbol's address. For that refer to 75 %const char* dlSymsNameFromValue(DLSyms* pSyms, void* value); /* symbol must be loaded */
78 \lstinline{dlFindSymbol}. \lstinline{dlSymsInit} will return a handle (or a null pointer 76 %\end{lstlisting}
79 on error) to the shared object specified by \lstinline{libPath}, to be used with the other dlSyms* functions. Note that contrary 77 %
80 to loading and linking libraries, no (OS-specific) rules for searching libraries in library paths, etc. apply. The handle must be freed with 78 %
81 \lstinline{dlSymsCleanup}. \lstinline{dlSymsCount} returns the number of 79 %These functions can be used to iterate over symbols. Since they can be used on libraries that are not linked, they are made
82 symbols in the shared object, \lstinline{dlSymsName} and \lstinline{dlSymsNameFromValue} 80 %for symbol name lookups, not to get a symbol's address. For that refer to
83 are used to lookup symbol names using an index or symbol's address, respectively, 81 %\lstinline{dlFindSymbol}. \lstinline{dlSymsInit} will return a handle (or a null pointer
84 returning a null pointer on error. The names are returned as they would appear 82 %on error) to the shared object specified by \lstinline{libPath}, to be used with the other dlSyms* functions. Note that contrary
85 in C source code (mangled if C++, etc.). The address passed to \lstinline{dlSymsNameFromValue} 83 %to loading and linking libraries, no (OS-specific) rules for searching libraries in library paths, etc. apply. The handle must be freed with
86 must point to a loaded symbol. 84 %\lstinline{dlSymsCleanup}. \lstinline{dlSymsCount} returns the number of
87 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 %