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. Use the :mod:`ctypes` 12 module instead. 13 14 .. sectionauthor:: Moshe Zadka <moshez (a] zadka.site.co.il> 15 16 The :mod:`dl` module defines an interface to the :c:func:`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 :c:type:`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 :c:type:`long`, which is a 113 Python integer. 114 115
