Doc/library/dl.rst

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