Doc/lib/libdl.tex

   1 \section{\module{dl} ---
   2          Call C functions in shared objects}
   3 \declaremodule{extension}{dl}
   4   \platform{Unix} %?????????? Anyone????????????
   5 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
   6 \modulesynopsis{Call C functions in shared objects.}
   7
   8 The \module{dl} module defines an interface to the
   9 \cfunction{dlopen()} function, which is the most common interface on
  10 \UNIX{} platforms for handling dynamically linked libraries. It allows
  11 the program to call arbitrary functions in such a library.
  12
  13 \warning{The \module{dl} module bypasses the Python type system and
  14 error handling. If used incorrectly it may cause segmentation faults,
  15 crashes or other incorrect behaviour.}
  16
  17 \note{This module will not work unless
  18 \code{sizeof(int) == sizeof(long) == sizeof(char *)}
  19 If this is not the case, \exception{SystemError} will be raised on
  20 import.}
  21
  22 The \module{dl} module defines the following function:
  23
  24 \begin{funcdesc}{open}{name\optional{, mode\code{ = RTLD_LAZY}}}
  25 Open a shared object file, and return a handle. Mode
  26 signifies late binding (\constant{RTLD_LAZY}) or immediate binding
  27 (\constant{RTLD_NOW}). Default is \constant{RTLD_LAZY}. Note that some
  28 systems do not support \constant{RTLD_NOW}.
  29
  30 Return value is a \class{dlobject}.
  31 \end{funcdesc}
  32
  33 The \module{dl} module defines the following constants:
  34
  35 \begin{datadesc}{RTLD_LAZY}
  36 Useful as an argument to \function{open()}.
  37 \end{datadesc}
  38
  39 \begin{datadesc}{RTLD_NOW}
  40 Useful as an argument to \function{open()}.  Note that on systems
  41 which do not support immediate binding, this constant will not appear
  42 in the module. For maximum portability, use \function{hasattr()} to
  43 determine if the system supports immediate binding.
  44 \end{datadesc}
  45
  46 The \module{dl} module defines the following exception:
  47
  48 \begin{excdesc}{error}
  49 Exception raised when an error has occurred inside the dynamic loading
  50 and linking routines.
  51 \end{excdesc}
  52
  53 Example:
  54
  55 \begin{verbatim}
  56 >>> import dl, time
  57 >>> a=dl.open('/lib/libc.so.6')
  58 >>> a.call('time'), time.time()
  59 (929723914, 929723914.498)
  60 \end{verbatim}
  61
  62 This example was tried on a Debian GNU/Linux system, and is a good
  63 example of the fact that using this module is usually a bad alternative.
  64
  65 \subsection{Dl Objects \label{dl-objects}}
  66
  67 Dl objects, as returned by \function{open()} above, have the
  68 following methods:
  69
  70 \begin{methoddesc}{close}{}
  71 Free all resources, except the memory.
  72 \end{methoddesc}
  73
  74 \begin{methoddesc}{sym}{name}
  75 Return the pointer for the function named \var{name}, as a number, if
  76 it exists in the referenced shared object, otherwise \code{None}. This
  77 is useful in code like:
  78
  79 \begin{verbatim}
  80 >>> if a.sym('time'):
  81 ...     a.call('time')
  82 ... else:
  83 ...     time.time()
  84 \end{verbatim}
  85
  86 (Note that this function will return a non-zero number, as zero is the
  87 \NULL{} pointer)
  88 \end{methoddesc}
  89
  90 \begin{methoddesc}{call}{name\optional{, arg1\optional{, arg2\ldots}}}
  91 Call the function named \var{name} in the referenced shared object.
  92 The arguments must be either Python integers, which will be
  93 passed as is, Python strings, to which a pointer will be passed,
  94 or \code{None}, which will be passed as \NULL.  Note that
  95 strings should only be passed to functions as \ctype{const char*}, as
  96 Python will not like its string mutated.
  97
  98 There must be at most 10 arguments, and arguments not given will be
  99 treated as \code{None}. The function's return value must be a C
 100 \ctype{long}, which is a Python integer.
 101 \end{methoddesc}