\section{\module{dl} --- Call C functions in shared objects}\declaremodule{extension}{dl} \platform{Unix} %?????????? Anyone????????????\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}\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 allowsthe 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 onimport.}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. Modesignifies late binding (\constant{RTLD_LAZY}) or immediate binding(\constant{RTLD_NOW}). Default is \constant{RTLD_LAZY}. Note that somesystems 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 systemswhich do not support immediate binding, this constant will not appearin the module. For maximum portability, use \function{hasattr()} todetermine 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 loadingand 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 goodexample 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 thefollowing 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, ifit exists in the referenced shared object, otherwise \code{None}. Thisis 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*}, asPython will not like its string mutated.There must be at most 10 arguments, and arguments not given will betreated as \code{None}. The function's return value must be a C\ctype{long}, which is a Python integer.\end{methoddesc}
\section{\module{dl} ---
Call C functions in shared objects}
\declaremodule{extension}{dl}
\platform{Unix} %?????????? Anyone????????????
\sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
\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}