# HG changeset patch
# User Tassilo Philipp
# Date 1493898849 -7200
# Node ID 2a77747a5496478cf3b09a6d789f42ca89d395e4
# Parent  85b61e8facfe523a18ba66782018c98f60768770
dynload doc:
- improved overall
- added dlGetLibraryPath description:
- BUGS section to manpage

diff -r 85b61e8facfe -r 2a77747a5496 doc/manual/manual_dynload_api.tex
--- 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,
diff -r 85b61e8facfe -r 2a77747a5496 dynload/dynload.3
--- a/dynload/dynload.3	Thu May 04 13:42:17 2017 +0200
+++ b/dynload/dynload.3	Thu May 04 13:54:09 2017 +0200
@@ -27,6 +27,8 @@
 .Fn dlFreeLibrary "DLLib * pLib"
 .Ft void *
 .Fn dlFindSymbol "DLLib * pLib" "const char * pSymbolName"
+.Ft int
+.Fn dlGetLibraryPath "DLLib * pLib" "char * sOut" "int bufSize"
 .Ft DLSyms*
 .Fn dlSymsInit "const char * libPath"
 .Ft void
@@ -52,7 +54,7 @@
 .Fn dlFindSymbol
 calls. Passing a null pointer for the
 .Ar libpath
-argument is valid, and returns a handle to the main executable of the calling code. Returns a null pointer on error.
+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.
 .Pp
 .Fn dlFreeLibrary 
 frees the loaded library with handle
@@ -65,13 +67,25 @@
 .Ar 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.).
 .Pp
-The dlSyms* functions can be used to iterate over symbols. Note that they are made
-for symbol name lookups, not to get a symbol's address. For that refer to
+.Fn dlGetLibraryPath
+can be used to get a copy of the path to the library loaded with handle
+.Ar pLib .
+The parameter
+.Ar sOut
+is a pointer to a buffer of size
+.Ar 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
+.Ar bufSize
+>= return value > 1, a null-terminted string with the path to the library should be in
+.Ar sOut .
+.Pp
+The dlSyms* 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 symbols' addresses. For that refer to
 .Fn dlFindSymbol .
 .Fn dlSymsInit
 will return a handle (or null pointer on error) to the shared object specified by
-.Ar libPath .
-The returned handle is to be used with the other dlSyms* functions. The handle must be freed with
+.Ar 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
 .Fn dlSymsCleanup .
 .Fn dlSymsCount
 returns the number of symbols in the shared object,
@@ -81,6 +95,11 @@
 are used to lookup symbol names using an index or symbol's address, respectively, returning a null pointer on error. The names are returned as they would appear in C source code (mangled if C++, etc.). The address passed to
 .Fn dlSymsNameFromValue
 must point to a loaded symbol.
+.Sh BUGS
+.Fn dlGetLibraryPath
+and
+.Fn dlSymsInit
+are not thread-safe on Darwin (macOS, iOS, ...).
 .Sh SEE ALSO
 .Xr dyncall 3 ,
 .Xr dyncallback 3