1Dynlink(3)                       OCaml library                      Dynlink(3)
2
3
4

NAME

6       Dynlink - Dynamic loading of .cmo, .cma and .cmxs files.
7

Module

9       Module   Dynlink
10

Documentation

12       Module Dynlink
13        : sig end
14
15
16       Dynamic loading of .cmo, .cma and .cmxs files.
17
18
19
20
21
22
23       val is_native : bool
24
25
26       true if the program is native, false if the program is bytecode.
27
28
29
30
31   Dynamic loading of compiled files
32       val loadfile : string -> unit
33
34       In  bytecode: load the given bytecode object file ( .cmo file) or byte‐
35       code library file ( .cma file), and link it with the  running  program.
36       In  native code: load the given OCaml plugin file (usually .cmxs ), and
37       link it with the running program.
38
39       All toplevel expressions in the loaded compilation units are evaluated.
40       No  facilities  are provided to access value names defined by the unit.
41       Therefore, the unit must itself register its entry points with the main
42       program  (or  a  previously-loaded library) e.g. by modifying tables of
43       functions.
44
45       An exception will be raised if the given library defines toplevel  mod‐
46       ules whose names clash with modules existing either in the main program
47       or a shared library previously loaded with  loadfile  .   Modules  from
48       shared  libraries  previously  loaded with loadfile_private are not in‐
49       cluded in this restriction.
50
51       The compilation units loaded by this function are added to the "allowed
52       units" list (see Dynlink.set_allowed_units ).
53
54
55
56       val loadfile_private : string -> unit
57
58       Same  as  loadfile  , except that the compilation units just loaded are
59       hidden (cannot be referenced) from other modules dynamically loaded af‐
60       terwards.
61
62       An  exception will be raised if the given library defines toplevel mod‐
63       ules whose names clash with modules existing in either the main program
64       or  a  shared  library  previously loaded with loadfile .  Modules from
65       shared libraries previously loaded with loadfile_private  are  not  in‐
66       cluded in this restriction.
67
68       An  exception will also be raised if the given library defines toplevel
69       modules whose name matches that of an interface depended on by a module
70       existing  in  either  the  main  program or a shared library previously
71       loaded with loadfile . This applies even if such dependency is  only  a
72       "module  alias"  dependency (i.e. just on the name rather than the con‐
73       tents of the interface).
74
75       The compilation units loaded by this function are not added to the "al‐
76       lowed units" list (see Dynlink.set_allowed_units ) since they cannot be
77       referenced from other compilation units.
78
79
80
81       val adapt_filename : string -> string
82
83       In bytecode, the identity function. In native code,  replace  the  last
84       extension with .cmxs .
85
86
87
88
89   Access control
90       val set_allowed_units : string list -> unit
91
92       Set  the  list  of  compilation units that may be referenced from units
93       that are dynamically loaded in the  future  to  be  exactly  the  given
94       value.
95
96       Initially all compilation units composing the program currently running
97       are available for reference  from  dynamically-linked  units.   set_al‐
98       lowed_units  can be used to restrict access to a subset of these units,
99       e.g. to the units that compose the API for dynamically-linked code, and
100       prevent  access  to  all other units, e.g. private, internal modules of
101       the running program.
102
103       Note that Dynlink.loadfile changes the allowed-units list.
104
105
106
107       val allow_only : string list -> unit
108
109
110       allow_only units sets the list of allowed units to be the  intersection
111       of  the existing allowed units and the given list of units.  As such it
112       can never increase the set of allowed units.
113
114
115
116       val prohibit : string list -> unit
117
118
119       prohibit units prohibits dynamically-linked units from referencing  the
120       units named in list units by removing such units from the allowed units
121       list.  This can be used to prevent access to selected units, e.g.  pri‐
122       vate, internal modules of the running program.
123
124
125
126       val main_program_units : unit -> string list
127
128       Return  the  list of compilation units that form the main program (i.e.
129       are not dynamically linked).
130
131
132
133       val public_dynamically_loaded_units : unit -> string list
134
135       Return the list of compilation units that have been dynamically  loaded
136       via  loadfile  (and  not via loadfile_private ).  Note that compilation
137       units loaded dynamically cannot be unloaded.
138
139
140
141       val all_units : unit -> string list
142
143       Return the list of compilation units that form  the  main  program  to‐
144       gether  with  those that have been dynamically loaded via loadfile (and
145       not via loadfile_private ).
146
147
148
149       val allow_unsafe_modules : bool -> unit
150
151       Govern whether unsafe  object  files  are  allowed  to  be  dynamically
152       linked.  A  compilation unit is 'unsafe' if it contains declarations of
153       external functions, which can break type safety.  By  default,  dynamic
154       linking  of  unsafe  object  files is not allowed. In native code, this
155       function does nothing; object files with external functions are  always
156       allowed to be dynamically linked.
157
158
159
160
161   Error reporting
162       type linking_error = private
163        | Undefined_global of string
164        | Unavailable_primitive of string
165        | Uninitialized_global of string
166
167
168
169
170       type error = private
171        | Not_a_bytecode_file of string
172        | Inconsistent_import of string
173        | Unavailable_unit of string
174        | Unsafe_file
175        | Linking_error of string * linking_error
176        | Corrupted_interface of string
177        | Cannot_open_dynamic_library of exn
178        | Library's_module_initializers_failed of exn
179        | Inconsistent_implementation of string
180        | Module_already_loaded of string
181        | Private_library_cannot_implement_interface of string
182
183
184
185
186
187       exception Error of error
188
189
190       Errors  in  dynamic linking are reported by raising the Error exception
191       with a description of the error.  A common case is the dynamic  library
192       not  being  found  on  the system: this is reported via Cannot_open_dy‐
193       namic_library (the enclosed exception may be platform-specific).
194
195
196
197       val error_message : error -> string
198
199       Convert an error description to a printable message.
200
201
202
203
204
205OCamldoc                          2023-07-20                        Dynlink(3)
Impressum