|
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 |
|
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. |
|
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 |
|
31 The :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 |
|
42 The :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 |
|
57 The :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 |
|
65 Example:: |
|
66 |
|
67 >>> import dl, time |
|
68 >>> a=dl.open('/lib/libc.so.6') |
|
69 >>> a.call('time'), time.time() |
|
70 (929723914, 929723914.498) |
|
71 |
|
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. |
|
74 |
|
75 |
|
76 .. _dl-objects: |
|
77 |
|
78 Dl Objects |
|
79 ---------- |
|
80 |
|
81 Dl 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 |