36.6. "dl" — Call C functions in shared objects
***********************************************

Deprecated since version 2.6: The "dl" module has been removed in
Python 3. 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.


36.6.1. 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.