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@zadka.site.co.il> 15 16The :mod:`dl` module defines an interface to the :c:func:`dlopen` function, which 17is the most common interface on Unix platforms for handling dynamically linked 18libraries. 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 31The :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 42The :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 57The :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 65Example:: 66 67 >>> import dl, time 68 >>> a=dl.open('/lib/libc.so.6') 69 >>> a.call('time'), time.time() 70 (929723914, 929723914.498) 71 72This example was tried on a Debian GNU/Linux system, and is a good example of 73the fact that using this module is usually a bad alternative. 74 75 76.. _dl-objects: 77 78Dl Objects 79---------- 80 81Dl 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