
``dl`` --- Call C functions in shared objects
*********************************************

Platform: Unix

*Platforms: *Unix

Deprecated since version 2.6: The ``dl`` module has been removed in
Python 3.0. Use the ``ctypes`` module instead.

The ``dl`` module defines an interface to the ``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 ``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 ``sizeof(int) == sizeof(long) ==
  sizeof(char *)`` If this is not the case, ``SystemError`` will be
  raised on import.

The ``dl`` module defines the following function:

dl.open(name[, mode=RTLD_LAZY])

   Open a shared object file, and return a handle. Mode signifies late
   binding (``RTLD_LAZY``) or immediate binding (``RTLD_NOW``).
   Default is ``RTLD_LAZY``. Note that some systems do not support
   ``RTLD_NOW``.

   Return value is a ``dlobject``.

The ``dl`` module defines the following constants:

dl.RTLD_LAZY

   Useful as an argument to ``open()``.

dl.RTLD_NOW

   Useful as an argument to ``open()``.  Note that on systems which do
   not support immediate binding, this constant will not appear in the
   module. For maximum portability, use ``hasattr()`` to determine if
   the system supports immediate binding.

The ``dl`` module defines the following exception:

exception dl.error

   Exception raised when an error has occurred inside the dynamic
   loading and linking routines.

Example:

   >>> import dl, time
   >>> a=dl.open('/lib/libc.so.6')
   >>> a.call('time'), time.time()
   (929723914, 929723914.498)

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.


Dl Objects
==========

Dl objects, as returned by ``open()`` above, have the following
methods:

dl.close()

   Free all resources, except the memory.

dl.sym(name)

   Return the pointer for the function named *name*, as a number, if
   it exists in the referenced shared object, otherwise ``None``. This
   is useful in code like:

      >>> if a.sym('time'):
      ...     a.call('time')
      ... else:
      ...     time.time()

   (Note that this function will return a non-zero number, as zero is
   the *NULL* pointer)

dl.call(name[, arg1[, arg2...]])

   Call the function named *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
   ``None``, which will be passed as *NULL*. Note that  strings should
   only be passed to functions as ``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 ``None``. The function's return value must be a C
   ``long``, which is a Python integer.
