# HG changeset patch
# User Tassilo Philipp
# Date 1492342479 -7200
# Node ID f8a6e60598ccc9fca80bd28cdeef483f4cc7d6d9
# Parent  318a9ffc2b8527a6dd3a5a8c3d9761d6d69c28da
- completed dynload API doc

diff -r 318a9ffc2b85 -r f8a6e60598cc doc/manual/manual_dynload_api.tex
--- a/doc/manual/manual_dynload_api.tex	Sun Apr 16 13:29:36 2017 +0200
+++ b/doc/manual/manual_dynload_api.tex	Sun Apr 16 13:34:39 2017 +0200
@@ -1,6 +1,6 @@
 %//////////////////////////////////////////////////////////////////////////////
 %
-% Copyright (c) 2007,2009 Daniel Adler <dadler@uni-goettingen.de>, 
+% Copyright (c) 2007-2017 Daniel Adler <dadler@uni-goettingen.de>, 
 %                         Tassilo Philipp <tphilipp@potion-studios.com>
 %
 % Permission to use, copy, modify, and distribute this software for any
@@ -26,7 +26,7 @@
 \subsection{Loading code}
 
 \begin{lstlisting}[language=c,label=dl-load]
-void* dlLoadLibrary(const char* libpath);
+DLLib* dlLoadLibrary(const char* libpath);
 void  dlFreeLibrary(void* libhandle);
 \end{lstlisting}
 
@@ -42,6 +42,29 @@
 void* dlFindSymbol(void* libhandle, const char* symbol);
 \end{lstlisting}
 
-returns a pointer to a symbol with name \lstinline{pSymbolName} in the
+This function returns a pointer to a symbol with name \lstinline{pSymbolName} in the
 library with handle \lstinline{pLib}, or returns a null pointer if the symbol cannot
-be found.
+be found. The name is specified as it would appear in C source code (mangled if C++, etc.).
+
+\subsection{Symbol iteration}
+
+\begin{lstlisting}[language=c]
+DLSyms*     dlSymsInit(const char* libPath);
+void        dlSymsCleanup(DLSyms* pSyms);
+int         dlSymsCount(DLSyms* pSyms);
+const char* dlSymsName(DLSyms* pSyms, int index);
+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
+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
+\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,
+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 \lstinline{dlSymsNameFromValue}
+must point to a loaded symbol.
+
diff -r 318a9ffc2b85 -r f8a6e60598cc dynload/dynload.3
--- a/dynload/dynload.3	Sun Apr 16 13:29:36 2017 +0200
+++ b/dynload/dynload.3	Sun Apr 16 13:34:39 2017 +0200
@@ -27,6 +27,16 @@
 .Fn dlFreeLibrary "DLLib * pLib"
 .Ft void *
 .Fn dlFindSymbol "DLLib * pLib" "const char * pSymbolName"
+.Ft DLSyms*
+.Fn dlSymsInit "const char * libPath"
+.Ft void
+.Fn dlSymsCleanup "DLSyms * pSyms"
+.Ft int
+.Fn dlSymsCount "DLSyms * pSyms"
+.Ft const char*
+.Fn dlSymsName "DLSyms * pSyms" "int index"
+.Ft const char*
+.Fn dlSymsNameFromValue "DLSyms * pSyms" "void * value"
 .Sh DESCRIPTION
 The
 .Nm
@@ -54,6 +64,23 @@
 in the library with handle
 .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 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
+.Fn dlSymsCleanup .
+.Fn dlSymsCount
+returns the number of symbols in the shared object,
+.Fn dlSymsName
+and
+.Fn dlSymsNameFromValue
+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 SEE ALSO
 .Xr dyncall 3 ,
 .Xr dyncallback 3