2 :mod:`dl` --- Call C functions in shared objects
3 ================================================
7 :synopsis: Call C functions in shared objects.
11 The :mod:`dl` module has been removed in Python 3.0. Use the :mod:`ctypes`
14 .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
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.
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
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.
31 The :mod:`dl` module defines the following function:
34 .. function:: open(name[, mode=RTLD_LAZY])
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`.
40 Return value is a :class:`dlobject`.
42 The :mod:`dl` module defines the following constants:
47 Useful as an argument to :func:`open`.
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
57 The :mod:`dl` module defines the following exception:
62 Exception raised when an error has occurred inside the dynamic loading and
68 >>> a=dl.open('/lib/libc.so.6')
69 >>> a.call('time'), time.time()
70 (929723914, 929723914.498)
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.
81 Dl objects, as returned by :func:`open` above, have the following methods:
84 .. method:: dl.close()
86 Free all resources, except the memory.
89 .. method:: dl.sym(name)
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::
99 (Note that this function will return a non-zero number, as zero is the *NULL*
103 .. method:: dl.call(name[, arg1[, arg2...]])
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.
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