\section{\module{dl} ---
         Call C functions in shared objects}
\declaremodule{extension}{dl}
  \platform{Unix} %?????????? Anyone????????????
\sectionauthor{Moshe Zadka}{[email protected]}
\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 arbitrary functions in such a library.

\warning{The \module{dl} module bypasses the Python type system and 
error handling. If used incorrectly it may cause segmentation faults,
crashes or other incorrect behaviour.}

\note{This module will not work unless
\code{sizeof(int) == sizeof(long) == sizeof(char *)}
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
systems do not support \constant{RTLD_NOW}.

Return value is a \class{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 occurred 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}