Dynamic loading of object files.
In bytecode: load the given bytecode object file (
.cmo file) or bytecode library file (
.cma file), and link it with the running program. In native code: load the given OCaml plugin file (usually
.cmxs), and link it with the running program. All toplevel expressions in the loaded compilation units 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.
loadfile, except that the compilation units just loaded are hidden (cannot be referenced) from other modules dynamically loaded afterwards.
In bytecode, the identity function. In native code, replace the last extension with
allow_only units restricts the compilation units that dynamically-linked units can reference: it forbids all references to units other than those named in the list
units. References to any other compilation unit will cause a
Unavailable_unit error during
Initially (or after calling
default_available_units) all compilation units composing the program currently running are available for reference from dynamically-linked units.
allow_only can be used to restrict access to a subset of these units, e.g. to the units that compose the API for dynamically-linked code, and prevent access to all other units, e.g. private, internal modules of the running program. If
allow_only is called several times, access will be restricted to the intersection of the given lists (i.e. a call to
allow_only can never increase the set of available units).
prohibit units prohibits dynamically-linked units from referencing the units named in list
units. This can be used to prevent access to selected units, e.g. private, internal modules of the running program.
Reset the set of units that can be referenced from dynamically-linked code to its default value, that is, all units composing the currently running program.
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. In native code, this function does nothing; object files with external functions are always allowed to be dynamically linked.
clear_available_unitsshould not be used in new programs, since the default initialization of allowed units, along with the
prohibitfunction, provides a better, safer mechanism to control access to program units. The three functions below are provided for backward compatibility only and are not available in native code.
add_interfaces units path grants dynamically-linked object files access to the compilation units named in list
units. The interfaces (
.cmi files) for these units are searched in
path (a list of directory names).
val add_available_units : (string * Digest.t) list -> unit
Dynlink.add_interfaces, but instead of searching
.cmi files to find the unit interfaces, uses the interface digests given for each unit. This way, the
.cmi interface files need not be available at run-time. The digests can be extracted from
.cmi files using the
extract_crc program installed in the OCaml standard library directory.
Empty the list of compilation units accessible to dynamically-linked programs.
Dynlinklibrary. This function is called automatically when needed.
type error =
| Not_a_bytecode_file of string
| Inconsistent_import of string
| Unavailable_unit of string
| Linking_error of string * linking_error
| Corrupted_interface of string
| File_not_found of string
| Cannot_open_dll of string
| Inconsistent_implementation of string
exception Error of error
Errors in dynamic linking are reported by raising the
Error exception with a description of the error.
val error_message : error -> string
Convert an error description to a printable message.