Mercurial > pub > dyncall > dyncall

comparison doc/manual/manual_dynload_api.tex @ 243:2a77747a5496

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
dynload doc: - improved overall - added dlGetLibraryPath description: - BUGS section to manpage
author Tassilo Philipp
date Thu, 04 May 2017 13:54:09 +0200
parents f8a6e60598cc
children ab23f9f2934a
comparison
equal deleted inserted replaced
242:85b61e8facfe 243:2a77747a5496
30 void dlFreeLibrary(void* libhandle); 30 void dlFreeLibrary(void* libhandle);
31 \end{lstlisting} 31 \end{lstlisting}
32 32
33 \lstinline{dlLoadLibrary} loads a dynamic library at \lstinline{libpath} 33 \lstinline{dlLoadLibrary} loads a dynamic library at \lstinline{libpath}
34 and returns a handle to it for use in \lstinline{dlFreeLibrary} and 34 and returns a handle to it for use in \lstinline{dlFreeLibrary} and
35 \lstinline{dlFindSymbol} calls. 35 \lstinline{dlFindSymbol} calls. Passing a null pointer for the \lstinline{libpath}
36 argument is valid, and returns a handle to the main executable of the calling code.
37 Also, searching libraries in library paths (e.g. by just passing the library's leaf
38 name) should work, however, they are OS specific. Returns a null pointer on error.
36 39
37 \lstinline{dlFreeLibrary} frees the loaded library with handle \lstinline{pLib}. 40 \lstinline{dlFreeLibrary} frees the loaded library with handle \lstinline{pLib}.
38 41
39 \subsection{Retrieving functions} 42 \subsection{Retrieving functions}
40 43
44 47
45 This function returns a pointer to a symbol with name \lstinline{pSymbolName} in the 48 This function returns a pointer to a symbol with name \lstinline{pSymbolName} in the
46 library with handle \lstinline{pLib}, or returns a null pointer if the symbol cannot 49 library with handle \lstinline{pLib}, or returns a null pointer if the symbol cannot
47 be found. The name is specified as it would appear in C source code (mangled if C++, etc.). 50 be found. The name is specified as it would appear in C source code (mangled if C++, etc.).
48 51
52 \subsection{Misc functions}
53 \begin{lstlisting}[language=c]
54 int dlGetLibraryPath(DLLib* pLib, char* sOut, int bufSize);
55 \end{lstlisting}
56
57 This function can be used to get a copy of the path to the library loaded with handle
58 \lstinline{pLib}. The parameter \lstinline{sOut} is a pointer to a buffer of size
59 \lstinline{bufSize} (in bytes), to hold the output string. The return value is the size
60 of the buffer (in bytes) needed to hold the null-terminated string, or 0 if it can't be
61 looked up. If \lstinline{bufSize} >= return value > 1, a null-terminted string with the
62 path to the library should be in \lstinline{sOut}.
63
49 \subsection{Symbol iteration} 64 \subsection{Symbol iteration}
50 65
51 \begin{lstlisting}[language=c] 66 \begin{lstlisting}[language=c]
52 DLSyms* dlSymsInit(const char* libPath); 67 DLSyms* dlSymsInit(const char* libPath);
53 void dlSymsCleanup(DLSyms* pSyms); 68 void dlSymsCleanup(DLSyms* pSyms);
54 int dlSymsCount(DLSyms* pSyms); 69 int dlSymsCount(DLSyms* pSyms);
55 const char* dlSymsName(DLSyms* pSyms, int index); 70 const char* dlSymsName(DLSyms* pSyms, int index);
56 const char* dlSymsNameFromValue(DLSyms* pSyms, void* value); /* symbol must be loaded */ 71 const char* dlSymsNameFromValue(DLSyms* pSyms, void* value); /* symbol must be loaded */
57 \end{lstlisting} 72 \end{lstlisting}
58 73
59 These functions can be used to iterate over symbols. Note that they are made 74
75 These functions can be used to iterate over symbols. Since they can be used on libraries that are not linked, they are made
60 for symbol name lookups, not to get a symbol's address. For that refer to 76 for symbol name lookups, not to get a symbol's address. For that refer to
61 \lstinline{dlFindSymbol}. \lstinline{dlSymsInit} will return a handle (or a null pointer 77 \lstinline{dlFindSymbol}. \lstinline{dlSymsInit} will return a handle (or a null pointer
62 on error) to the shared object specified by \lstinline{libPath}. The returned 78 on error) to the shared object specified by \lstinline{libPath}, to be used with the other dlSyms* functions. Note that contrary
63 handle is to be used with the other functions. The handle must be freed with 79 to loading and linking libraries, no (OS-specific) rules for searching libraries in library paths, etc. apply. The handle must be freed with
64 \lstinline{dlSymsCleanup}. \lstinline{dlSymsCount} returns the number of 80 \lstinline{dlSymsCleanup}. \lstinline{dlSymsCount} returns the number of
65 symbols in the shared object, \lstinline{dlSymsName} and \lstinline{dlSymsNameFromValue} 81 symbols in the shared object, \lstinline{dlSymsName} and \lstinline{dlSymsNameFromValue}
66 are used to lookup symbol names using an index or symbol's address, respectively, 82 are used to lookup symbol names using an index or symbol's address, respectively,
67 returning a null pointer on error. The names are returned as they would appear 83 returning a null pointer on error. The names are returned as they would appear
68 in C source code (mangled if C++, etc.). The address passed to \lstinline{dlSymsNameFromValue} 84 in C source code (mangled if C++, etc.). The address passed to \lstinline{dlSymsNameFromValue}