Documentation for dl module from Moshe.

This commit is contained in:
Fred Drake 1999-07-01 20:40:21 +00:00
parent 44a7a7c5d0
commit 4c8d83f311
1 changed files with 99 additions and 0 deletions

99
Doc/lib/libdl.tex Normal file
View File

@ -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}