1Dynlink(3) OCaml library Dynlink(3)
2
6 Dynlink - Dynamic loading of .cmo, .cma and .cmxs files.
7
9 Module Dynlink
10
12 Module Dynlink
13 : sig end
14 Dynamic loading of .cmo, .cma and .cmxs files.
17 val is_native : bool
24 true if the program is native, false if the program is bytecode.
27 Dynamic loading of compiled files
32 val loadfile : string -> unit
33 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 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 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 The compilation units loaded by this function are added to the "allowed
52 units" list (see Dynlink.set_allowed_units ).
53 val loadfile_private : string -> unit
57 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 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 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 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 val adapt_filename : string -> string
82 In bytecode, the identity function. In native code, replace the last
84 extension with .cmxs .
85 Access control
90 val set_allowed_units : string list -> unit
91 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 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 Note that Dynlink.loadfile changes the allowed-units list.
104 val allow_only : string list -> unit
108 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 val prohibit : string list -> unit
117 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 val main_program_units : unit -> string list
127 Return the list of compilation units that form the main program (i.e.
129 are not dynamically linked).
130 val public_dynamically_loaded_units : unit -> string list
134 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 val all_units : unit -> string list
142 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 val allow_unsafe_modules : bool -> unit
150 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 Error reporting
162 type linking_error = private
163 | Undefined_global of string
164 | Unavailable_primitive of string
165 | Uninitialized_global of string
166 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 exception Error of error
188 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 val error_message : error -> string
198 Convert an error description to a printable message.
200OCamldoc 2023-01-23 Dynlink(3)