ref: 5b7d8e1f6fb4167e354545fef7e6dd6676986441
dir: /sys/src/cmd/python/Doc/lib/libdl.tex/
\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}