diff options
Diffstat (limited to 'Doc/lib/libdl.tex')
-rw-r--r-- | Doc/lib/libdl.tex | 101 |
1 files changed, 0 insertions, 101 deletions
diff --git a/Doc/lib/libdl.tex b/Doc/lib/libdl.tex deleted file mode 100644 index d4a799e..0000000 --- a/Doc/lib/libdl.tex +++ /dev/null @@ -1,101 +0,0 @@ -\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}[dl]{close}{} -Free all resources, except the memory. -\end{methoddesc} - -\begin{methoddesc}[dl]{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}[dl]{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} |