1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset= ISO-8859-1">
<TITLE>
The dynlink library: dynamic loading and linking of object files
</TITLE>
</HEAD>
<BODY >
<A HREF="manual065.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual067.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
<HR>
<H1>Chapter 24: The dynlink library: dynamic loading and linking of object files</H1>
The <TT>dynlink</TT> library supports type-safe dynamic loading and linking
of bytecode object files (<TT>.cmo</TT> and <TT>.cma</TT> files) in a running
bytecode program. Type safety is ensured by limiting the set of
modules from the running program that the loaded object file can
access, and checking that the running program and the loaded object
file have been compiled against the same interfaces for these modules.<BR>
<BR>
Programs that use the <TT>dynlink</TT> library simply need to link
<TT>dynlink.cma</TT> with their object files and other libraries. Linking in
``custom runtime'' mode is not necessary. Dynamic linking is
available only to bytecode programs compiled with <TT>ocamlc</TT>, not to
native-code programs compiled with <TT>ocamlopt</TT>.<BR>
<BR>
<H2>24.1 Module <TT>Dynlink</TT>: dynamic loading of bytecode object files</H2><A NAME="s:Dynlink"></A>
<A NAME="@manual890"></A><PRE>
val init : unit -> unit
</PRE>
<A NAME="@manual891"></A><BLOCKQUOTE>
Initialize the library. Must be called before <CODE>loadfile</CODE>.
</BLOCKQUOTE>
<PRE>
val loadfile : string -> unit
</PRE>
<A NAME="@manual892"></A><BLOCKQUOTE>
Load the given bytecode object file and link it.
All toplevel expressions in the loaded compilation unit
are evaluated. No facilities are provided to
access value names defined by the unit. Therefore, the unit
must register itself its entry points with the main program,
e.g. by modifying tables of functions.
</BLOCKQUOTE>
<PRE>
val loadfile_private : string -> unit
</PRE>
<A NAME="@manual893"></A><BLOCKQUOTE>
Same as <CODE>loadfile</CODE>, except that the module loaded is not
made available to other modules dynamically loaded afterwards.
</BLOCKQUOTE>
<PRE>
val add_interfaces : string list -> string list -> unit
</PRE>
<A NAME="@manual894"></A><BLOCKQUOTE>
<CODE>add_interfaces units path</CODE> grants dynamically-linked object
files access to the compilation units named in list <CODE>units</CODE>.
The interfaces (<CODE>.cmi</CODE> files) for these units are searched in
<CODE>path</CODE> (a list of directory names). Initially, dynamically-linked
object files do not have access to any of the compilation
units composing the running program, not even the standard library.
<CODE>add_interfaces</CODE> or <CODE>add_available_units</CODE> (see below) must be
called to grant access to some of the units.
</BLOCKQUOTE>
<PRE>
val add_available_units : (string * Digest.t) list -> unit
</PRE>
<A NAME="@manual895"></A><BLOCKQUOTE>
Same as <CODE>add_interfaces</CODE>, but instead of searching <CODE>.cmi</CODE> files
to find the unit interfaces, uses the interface digests given
for each unit. This way, the <CODE>.cmi</CODE> interface files need not be
available at run-time. The digests can be extracted from <CODE>.cmi</CODE>
files using the <CODE>extract_crc</CODE> program installed in the
Objective Caml standard library directory.
</BLOCKQUOTE>
<PRE>
val clear_available_units : unit -> unit
</PRE>
<A NAME="@manual896"></A><BLOCKQUOTE>
Clear the list of compilation units accessible to dynamically-linked
programs.
</BLOCKQUOTE>
<PRE>
val allow_unsafe_modules : bool -> unit
</PRE>
<A NAME="@manual897"></A><BLOCKQUOTE>
Govern whether unsafe object files are allowed to be
dynamically linked. A compilation unit is ``unsafe'' if it contains
declarations of external functions, which can break type safety.
By default, dynamic linking of unsafe object files is
not allowed.
</BLOCKQUOTE>
<PRE>
type linking_error =
Undefined_global of string
| Unavailable_primitive of string
type error =
Not_a_bytecode_file of string
| Inconsistent_import of string
| Unavailable_unit of string
| Unsafe_file
| Linking_error of string * linking_error
| Corrupted_interface of string
exception Error of error
</PRE>
<A NAME="@manual898"></A><BLOCKQUOTE>
Errors in dynamic linking are reported by raising the <CODE>Error</CODE>
exception with a description of the error.
</BLOCKQUOTE>
<PRE>
val error_message: error -> string
</PRE>
<A NAME="@manual899"></A><BLOCKQUOTE>
Convert an error description to a printable message.
</BLOCKQUOTE>
<HR>
<A HREF="manual065.html"><IMG SRC ="previous_motif.gif" ALT="Previous"></A>
<A HREF="manual067.html"><IMG SRC ="next_motif.gif" ALT="Next"></A>
<A HREF="index.html"><IMG SRC ="contents_motif.gif" ALT="Contents"></A>
</BODY>
</HTML>
|
