/Doc/library/dl.rst

http://unladen-swallow.googlecode.com/ · ReStructuredText · 114 lines · 69 code · 45 blank · 0 comment · 0 complexity · cd01cc198dc37eb67760d5608fcc9718 MD5 · raw file

  1. :mod:`dl` --- Call C functions in shared objects
  2. ================================================
  3. .. module:: dl
  4. :platform: Unix
  5. :synopsis: Call C functions in shared objects.
  6. :deprecated:
  7. .. deprecated:: 2.6
  8. The :mod:`dl` module has been removed in Python 3.0. Use the :mod:`ctypes`
  9. module instead.
  10. .. sectionauthor:: Moshe Zadka <moshez@zadka.site.co.il>
  11. The :mod:`dl` module defines an interface to the :cfunc:`dlopen` function, which
  12. is the most common interface on Unix platforms for handling dynamically linked
  13. libraries. It allows the program to call arbitrary functions in such a library.
  14. .. warning::
  15. The :mod:`dl` module bypasses the Python type system and error handling. If
  16. used incorrectly it may cause segmentation faults, crashes or other incorrect
  17. behaviour.
  18. .. note::
  19. This module will not work unless ``sizeof(int) == sizeof(long) == sizeof(char
  20. *)`` If this is not the case, :exc:`SystemError` will be raised on import.
  21. The :mod:`dl` module defines the following function:
  22. .. function:: open(name[, mode=RTLD_LAZY])
  23. Open a shared object file, and return a handle. Mode signifies late binding
  24. (:const:`RTLD_LAZY`) or immediate binding (:const:`RTLD_NOW`). Default is
  25. :const:`RTLD_LAZY`. Note that some systems do not support :const:`RTLD_NOW`.
  26. Return value is a :class:`dlobject`.
  27. The :mod:`dl` module defines the following constants:
  28. .. data:: RTLD_LAZY
  29. Useful as an argument to :func:`open`.
  30. .. data:: RTLD_NOW
  31. Useful as an argument to :func:`open`. Note that on systems which do not
  32. support immediate binding, this constant will not appear in the module. For
  33. maximum portability, use :func:`hasattr` to determine if the system supports
  34. immediate binding.
  35. The :mod:`dl` module defines the following exception:
  36. .. exception:: error
  37. Exception raised when an error has occurred inside the dynamic loading and
  38. linking routines.
  39. Example::
  40. >>> import dl, time
  41. >>> a=dl.open('/lib/libc.so.6')
  42. >>> a.call('time'), time.time()
  43. (929723914, 929723914.498)
  44. This example was tried on a Debian GNU/Linux system, and is a good example of
  45. the fact that using this module is usually a bad alternative.
  46. .. _dl-objects:
  47. Dl Objects
  48. ----------
  49. Dl objects, as returned by :func:`open` above, have the following methods:
  50. .. method:: dl.close()
  51. Free all resources, except the memory.
  52. .. method:: dl.sym(name)
  53. Return the pointer for the function named *name*, as a number, if it exists in
  54. the referenced shared object, otherwise ``None``. This is useful in code like::
  55. >>> if a.sym('time'):
  56. ... a.call('time')
  57. ... else:
  58. ... time.time()
  59. (Note that this function will return a non-zero number, as zero is the *NULL*
  60. pointer)
  61. .. method:: dl.call(name[, arg1[, arg2...]])
  62. Call the function named *name* in the referenced shared object. The arguments
  63. must be either Python integers, which will be passed as is, Python strings, to
  64. which a pointer will be passed, or ``None``, which will be passed as *NULL*.
  65. Note that strings should only be passed to functions as :ctype:`const char\*`,
  66. as Python will not like its string mutated.
  67. There must be at most 10 arguments, and arguments not given will be treated as
  68. ``None``. The function's return value must be a C :ctype:`long`, which is a
  69. Python integer.