Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libdl.tex @ 21467:4e35fa5d5708 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.
author Fred Drake <fdrake@acm.org>
date Tue, 18 Dec 2001 16:31:08 +0000
parents bc02c3b09626
children c3b2cd6ef27f 070bb421a303
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
11092
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
1 \section{\module{dl} ---
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
2 Call C functions in shared objects}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
3 \declaremodule{extension}{dl}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
4 \platform{Unix} %?????????? Anyone????????????
15467
d7864345b1c8 Update Moshe Zadka's email address to one works and might last a while.
Fred Drake <fdrake@acm.org>
parents: 13625
diff changeset
5 \sectionauthor{Moshe Zadka}{moshez@zadka.site.co.il}
11092
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
6 \modulesynopsis{Call C functions in shared objects.}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
7
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
8 The \module{dl} module defines an interface to the
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
9 \cfunction{dlopen()} function, which is the most common interface on
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
10 \UNIX{} platforms for handling dynamically linked libraries. It allows
13625
fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope
Thomas Wouters <thomas@python.org>
parents: 11092
diff changeset
11 the program to call arbitrary functions in such a library.
11092
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
12
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 15467
diff changeset
13 \note{This module will not work unless
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 15467
diff changeset
14 \code{sizeof(int) == sizeof(long) == sizeof(char *)}
11092
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
15 If this is not the case, \exception{SystemError} will be raised on
20580
376ee174ecd0 Use the \note and \warning macros where appropriate.
Fred Drake <fdrake@acm.org>
parents: 15467
diff changeset
16 import.}
11092
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
17
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
18 The \module{dl} module defines the following function:
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
19
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
20 \begin{funcdesc}{open}{name\optional{, mode\code{ = RTLD_LAZY}}}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
21 Open a shared object file, and return a handle. Mode
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
22 signifies late binding (\constant{RTLD_LAZY}) or immediate binding
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
23 (\constant{RTLD_NOW}). Default is \constant{RTLD_LAZY}. Note that some
13625
fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope
Thomas Wouters <thomas@python.org>
parents: 11092
diff changeset
24 systems do not support \constant{RTLD_NOW}.
11092
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
25
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
26 Return value is a \pytype{dlobject}.
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
27 \end{funcdesc}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
28
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
29 The \module{dl} module defines the following constants:
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
30
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
31 \begin{datadesc}{RTLD_LAZY}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
32 Useful as an argument to \function{open()}.
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
33 \end{datadesc}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
34
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
35 \begin{datadesc}{RTLD_NOW}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
36 Useful as an argument to \function{open()}. Note that on systems
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
37 which do not support immediate binding, this constant will not appear
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
38 in the module. For maximum portability, use \function{hasattr()} to
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
39 determine if the system supports immediate binding.
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
40 \end{datadesc}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
41
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
42 The \module{dl} module defines the following exception:
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
43
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
44 \begin{excdesc}{error}
13625
fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope
Thomas Wouters <thomas@python.org>
parents: 11092
diff changeset
45 Exception raised when an error has occurred inside the dynamic loading
11092
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
46 and linking routines.
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
47 \end{excdesc}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
48
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
49 Example:
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
50
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
51 \begin{verbatim}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
52 >>> import dl, time
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
53 >>> a=dl.open('/lib/libc.so.6')
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
54 >>> a.call('time'), time.time()
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
55 (929723914, 929723914.498)
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
56 \end{verbatim}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
57
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
58 This example was tried on a Debian GNU/Linux system, and is a good
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
59 example of the fact that using this module is usually a bad alternative.
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
60
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
61 \subsection{Dl Objects \label{dl-objects}}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
62
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
63 Dl objects, as returned by \function{open()} above, have the
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
64 following methods:
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
65
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
66 \begin{methoddesc}{close}{}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
67 Free all resources, except the memory.
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
68 \end{methoddesc}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
69
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
70 \begin{methoddesc}{sym}{name}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
71 Return the pointer for the function named \var{name}, as a number, if
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
72 it exists in the referenced shared object, otherwise \code{None}. This
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
73 is useful in code like:
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
74
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
75 \begin{verbatim}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
76 >>> if a.sym('time'):
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
77 ... a.call('time')
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
78 ... else:
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
79 ... time.time()
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
80 \end{verbatim}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
81
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
82 (Note that this function will return a non-zero number, as zero is the
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
83 \NULL{} pointer)
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
84 \end{methoddesc}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
85
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
86 \begin{methoddesc}{call}{name\optional{, arg1\optional{, arg2\ldots}}}
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
87 Call the function named \var{name} in the referenced shared object.
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
88 The arguments must be either Python integers, which will be
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
89 passed as is, Python strings, to which a pointer will be passed,
21062
bc02c3b09626 Clean up some markup cruft. A number of the macros that take no
Fred Drake <fdrake@acm.org>
parents: 20580
diff changeset
90 or \code{None}, which will be passed as \NULL. Note that
11092
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
91 strings should only be passed to functions as \ctype{const char*}, as
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
92 Python will not like its string mutated.
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
93
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
94 There must be at most 10 arguments, and arguments not given will be
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
95 treated as \code{None}. The function's return value must be a C
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
96 \ctype{long}, which is a Python integer.
7029e18b4f11 Documentation for dl module from Moshe.
Fred Drake <fdrake@acm.org>
parents:
diff changeset
97 \end{methoddesc}