Fred Drake | 4c8d83f | 1999-07-01 20:40:21 +0000 | [diff] [blame] | 1 | \section{\module{dl} --- |
| 2 | Call C functions in shared objects} |
| 3 | \declaremodule{extension}{dl} |
| 4 | \platform{Unix} %?????????? Anyone???????????? |
Fred Drake | 57657bc | 2000-12-01 15:25:23 +0000 | [diff] [blame] | 5 | \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il} |
Fred Drake | 4c8d83f | 1999-07-01 20:40:21 +0000 | [diff] [blame] | 6 | \modulesynopsis{Call C functions in shared objects.} |
| 7 | |
| 8 | The \module{dl} module defines an interface to the |
| 9 | \cfunction{dlopen()} function, which is the most common interface on |
| 10 | \UNIX{} platforms for handling dynamically linked libraries. It allows |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 11 | the program to call arbitrary functions in such a library. |
Fred Drake | 4c8d83f | 1999-07-01 20:40:21 +0000 | [diff] [blame] | 12 | |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 13 | \note{This module will not work unless |
| 14 | \code{sizeof(int) == sizeof(long) == sizeof(char *)} |
Fred Drake | 4c8d83f | 1999-07-01 20:40:21 +0000 | [diff] [blame] | 15 | If this is not the case, \exception{SystemError} will be raised on |
Fred Drake | 0aa811c | 2001-10-20 04:24:09 +0000 | [diff] [blame] | 16 | import.} |
Fred Drake | 4c8d83f | 1999-07-01 20:40:21 +0000 | [diff] [blame] | 17 | |
| 18 | The \module{dl} module defines the following function: |
| 19 | |
| 20 | \begin{funcdesc}{open}{name\optional{, mode\code{ = RTLD_LAZY}}} |
| 21 | Open a shared object file, and return a handle. Mode |
| 22 | signifies late binding (\constant{RTLD_LAZY}) or immediate binding |
| 23 | (\constant{RTLD_NOW}). Default is \constant{RTLD_LAZY}. Note that some |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 24 | systems do not support \constant{RTLD_NOW}. |
Fred Drake | 4c8d83f | 1999-07-01 20:40:21 +0000 | [diff] [blame] | 25 | |
| 26 | Return value is a \pytype{dlobject}. |
| 27 | \end{funcdesc} |
| 28 | |
| 29 | The \module{dl} module defines the following constants: |
| 30 | |
| 31 | \begin{datadesc}{RTLD_LAZY} |
| 32 | Useful as an argument to \function{open()}. |
| 33 | \end{datadesc} |
| 34 | |
| 35 | \begin{datadesc}{RTLD_NOW} |
| 36 | Useful as an argument to \function{open()}. Note that on systems |
| 37 | which do not support immediate binding, this constant will not appear |
| 38 | in the module. For maximum portability, use \function{hasattr()} to |
| 39 | determine if the system supports immediate binding. |
| 40 | \end{datadesc} |
| 41 | |
| 42 | The \module{dl} module defines the following exception: |
| 43 | |
| 44 | \begin{excdesc}{error} |
Thomas Wouters | f831663 | 2000-07-16 19:01:10 +0000 | [diff] [blame] | 45 | Exception raised when an error has occurred inside the dynamic loading |
Fred Drake | 4c8d83f | 1999-07-01 20:40:21 +0000 | [diff] [blame] | 46 | and linking routines. |
| 47 | \end{excdesc} |
| 48 | |
| 49 | Example: |
| 50 | |
| 51 | \begin{verbatim} |
| 52 | >>> import dl, time |
| 53 | >>> a=dl.open('/lib/libc.so.6') |
| 54 | >>> a.call('time'), time.time() |
| 55 | (929723914, 929723914.498) |
| 56 | \end{verbatim} |
| 57 | |
| 58 | This example was tried on a Debian GNU/Linux system, and is a good |
| 59 | example of the fact that using this module is usually a bad alternative. |
| 60 | |
| 61 | \subsection{Dl Objects \label{dl-objects}} |
| 62 | |
| 63 | Dl objects, as returned by \function{open()} above, have the |
| 64 | following methods: |
| 65 | |
| 66 | \begin{methoddesc}{close}{} |
| 67 | Free all resources, except the memory. |
| 68 | \end{methoddesc} |
| 69 | |
| 70 | \begin{methoddesc}{sym}{name} |
| 71 | Return the pointer for the function named \var{name}, as a number, if |
| 72 | it exists in the referenced shared object, otherwise \code{None}. This |
| 73 | is useful in code like: |
| 74 | |
| 75 | \begin{verbatim} |
| 76 | >>> if a.sym('time'): |
| 77 | ... a.call('time') |
| 78 | ... else: |
| 79 | ... time.time() |
| 80 | \end{verbatim} |
| 81 | |
| 82 | (Note that this function will return a non-zero number, as zero is the |
| 83 | \NULL{} pointer) |
| 84 | \end{methoddesc} |
| 85 | |
| 86 | \begin{methoddesc}{call}{name\optional{, arg1\optional{, arg2\ldots}}} |
| 87 | Call the function named \var{name} in the referenced shared object. |
| 88 | The arguments must be either Python integers, which will be |
| 89 | passed as is, Python strings, to which a pointer will be passed, |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 90 | or \code{None}, which will be passed as \NULL. Note that |
Fred Drake | 4c8d83f | 1999-07-01 20:40:21 +0000 | [diff] [blame] | 91 | strings should only be passed to functions as \ctype{const char*}, as |
| 92 | Python will not like its string mutated. |
| 93 | |
| 94 | There must be at most 10 arguments, and arguments not given will be |
| 95 | treated as \code{None}. The function's return value must be a C |
| 96 | \ctype{long}, which is a Python integer. |
| 97 | \end{methoddesc} |