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,