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