Mercurial > pub > dyncall > dyncall
diff doc/manual/manual_dynload_api.tex @ 243:2a77747a5496
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 |
line wrap: on
line diff
--- a/doc/manual/manual_dynload_api.tex Thu May 04 13:42:17 2017 +0200 +++ b/doc/manual/manual_dynload_api.tex Thu May 04 13:54:09 2017 +0200 @@ -32,7 +32,10 @@ \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{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}. @@ -46,6 +49,18 @@ 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} >= return value > 1, a null-terminted string with the +path to the library should be in \lstinline{sOut}. + \subsection{Symbol iteration} \begin{lstlisting}[language=c] @@ -56,11 +71,12 @@ 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 + +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}. The returned -handle is to be used with the other functions. The handle must be freed with +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,