mirror of
https://github.com/python/cpython.git
synced 2025-10-31 02:15:10 +00:00
97 lines
3.2 KiB
TeX
97 lines
3.2 KiB
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.
|
|
|
|
\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 \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 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}
|