1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
|
:mod:`dl` --- Call C functions in shared objects
================================================
.. module:: dl
:platform: Unix
:synopsis: Call C functions in shared objects.
:deprecated:
.. deprecated:: 2.6
The :mod:`dl` module has been removed in Python 3.0. Use the :mod:`ctypes`
module instead.
.. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
The :mod:`dl` module defines an interface to the :cfunc:`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 :mod:`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, :exc:`SystemError` will be raised on import.
The :mod:`dl` module defines the following function:
.. function:: open(name[, mode=RTLD_LAZY])
Open a shared object file, and return a handle. Mode signifies late binding
(:const:`RTLD_LAZY`) or immediate binding (:const:`RTLD_NOW`). Default is
:const:`RTLD_LAZY`. Note that some systems do not support :const:`RTLD_NOW`.
Return value is a :class:`dlobject`.
The :mod:`dl` module defines the following constants:
.. data:: RTLD_LAZY
Useful as an argument to :func:`open`.
.. data:: RTLD_NOW
Useful as an argument to :func:`open`. Note that on systems which do not
support immediate binding, this constant will not appear in the module. For
maximum portability, use :func:`hasattr` to determine if the system supports
immediate binding.
The :mod:`dl` module defines the following exception:
.. exception:: 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
----------
Dl objects, as returned by :func:`open` above, have the following methods:
.. method:: dl.close()
Free all resources, except the memory.
.. method:: 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)
.. method:: 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 :ctype:`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 :ctype:`long`, which is a
Python integer.
|
