/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
 16The :mod:`dl` module defines an interface to the :cfunc:`dlopen` function, which
 17is the most common interface on Unix platforms for handling dynamically linked
 18libraries. 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
 31The :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
 42The :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
 57The :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
 65Example::
 66
 67   >>> import dl, time
 68   >>> a=dl.open('/lib/libc.so.6')
 69   >>> a.call('time'), time.time()
 70   (929723914, 929723914.498)
 71
 72This example was tried on a Debian GNU/Linux system, and is a good example of
 73the fact that using this module is usually a bad alternative.
 74
 75
 76.. _dl-objects:
 77
 78Dl Objects
 79----------
 80
 81Dl 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