ref: 2fe3b28f86ed4aa291fb8a620b948abe9c6a1f84
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}{[email protected]} \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}