Documentation for dl module from Moshe.

Doc/lib/libdl.tex

@@ -0,0 +1,99 @@
+\section{\module{dl} ---
+         Call C functions in shared objects}
+\declaremodule{extension}{dl}
+  \platform{Unix} %?????????? Anyone????????????
+\sectionauthor{Moshe Zadka}{mzadka@geocities.com}
+\modulesynopsis{Call C functions in shared objects.}
+
+The \module{dl} module defines an interface to the
+\cfunction{dlopen()} function, which is the most common interface on
+\UNIX{} platforms for handling dynamically linked libraries. It allows
+the program to call arbitary functions in such a library.
+
+\strong{Note:} This module will not work unless
+\begin{verbatim}
+sizeof(int) == sizeof(long) == sizeof(char *)
+\end{verbatim}
+If this is not the case, \exception{SystemError} will be raised on
+import.
+
+The \module{dl} module defines the following function:
+
+\begin{funcdesc}{open}{name\optional{, mode\code{ = RTLD_LAZY}}}
+Open a shared object file, and return a handle. Mode
+signifies late binding (\constant{RTLD_LAZY}) or immediate binding
+(\constant{RTLD_NOW}). Default is \constant{RTLD_LAZY}. Note that some
+sytems do not support \constant{RTLD_NOW}.
+
+Return value is a \pytype{dlobject}.
+\end{funcdesc}
+
+The \module{dl} module defines the following constants:
+
+\begin{datadesc}{RTLD_LAZY}
+Useful as an argument to \function{open()}.
+\end{datadesc}
+
+\begin{datadesc}{RTLD_NOW}
+Useful as an argument to \function{open()}.  Note that on systems
+which do not support immediate binding, this constant will not appear
+in the module. For maximum portability, use \function{hasattr()} to
+determine if the system supports immediate binding.
+\end{datadesc}
+
+The \module{dl} module defines the following exception:
+
+\begin{excdesc}{error}
+Exception raised when an error has occured inside the dynamic loading
+and linking routines.
+\end{excdesc}
+
+Example:
+
+\begin{verbatim}
+>>> import dl, time
+>>> a=dl.open('/lib/libc.so.6')
+>>> a.call('time'), time.time()
+(929723914, 929723914.498)
+\end{verbatim}
+
+This example was tried on a Debian GNU/Linux system, and is a good
+example of the fact that using this module is usually a bad alternative.
+
+\subsection{Dl Objects \label{dl-objects}}
+
+Dl objects, as returned by \function{open()} above, have the
+following methods:
+
+\begin{methoddesc}{close}{}
+Free all resources, except the memory.
+\end{methoddesc}
+
+\begin{methoddesc}{sym}{name}
+Return the pointer for the function named \var{name}, as a number, if
+it exists in the referenced shared object, otherwise \code{None}. This
+is useful in code like:
+
+\begin{verbatim}
+>>> if a.sym('time'): 
+...     a.call('time')
+... else: 
+...     time.time()
+\end{verbatim}
+
+(Note that this function will return a non-zero number, as zero is the
+\NULL{} pointer)
+\end{methoddesc}
+
+\begin{methoddesc}{call}{name\optional{, arg1\optional{, arg2\ldots}}}
+Call the function named \var{name} in the referenced shared object.
+The arguments must be either Python integers, which will be 
+passed as is, Python strings, to which a pointer will be passed, 
+or \code{None}, which will be passed as \NULL{}. Note that 
+strings should only be passed to functions as \ctype{const char*}, as
+Python will not like its string mutated.
+
+There must be at most 10 arguments, and arguments not given will be
+treated as \code{None}. The function's return value must be a C
+\ctype{long}, which is a Python integer.
+\end{methoddesc}