36.6. dl — Call C functions in shared objects — Python 2.7.18 documentation

This document is for an old version of Python that is no longer supported. You should upgrade and read the Python documentation for the current stable release.

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