430 lines
7.8 KiB
HTML
430 lines
7.8 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of Dynlink</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>Dynlink</H1>
|
|
Section: OCaml library (3o)<BR>Updated: 2020-01-30<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
Dynlink - Dynamic loading of .cmo, .cma and .cmxs files.
|
|
<A NAME="lbAC"> </A>
|
|
<H2>Module</H2>
|
|
|
|
Module Dynlink
|
|
<A NAME="lbAD"> </A>
|
|
<H2>Documentation</H2>
|
|
|
|
<P>
|
|
Module
|
|
<B>Dynlink</B>
|
|
|
|
<BR> :
|
|
<B>sig end</B>
|
|
|
|
<P>
|
|
<P>
|
|
Dynamic loading of .cmo, .cma and .cmxs files.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val is_native </I>
|
|
|
|
:
|
|
<B>bool</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>true</B>
|
|
|
|
if the program is native,
|
|
<B>false</B>
|
|
|
|
if the program is bytecode.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H3>Dynamic loading of compiled files</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val loadfile </I>
|
|
|
|
:
|
|
<B>string -> unit</B>
|
|
|
|
<P>
|
|
In bytecode: load the given bytecode object file (
|
|
<B>.cmo</B>
|
|
|
|
file) or
|
|
bytecode library file (
|
|
<B>.cma</B>
|
|
|
|
file), and link it with the running
|
|
program. In native code: load the given OCaml plugin file (usually
|
|
<B>.cmxs</B>
|
|
|
|
), and link it with the running program.
|
|
<P>
|
|
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 itself register its entry points with the main program (or a
|
|
previously-loaded library) e.g. by modifying tables of functions.
|
|
<P>
|
|
An exception will be raised if the given library defines toplevel
|
|
modules whose names clash with modules existing either in the main
|
|
program or a shared library previously loaded with
|
|
<B>loadfile</B>
|
|
|
|
.
|
|
Modules from shared libraries previously loaded with
|
|
<B>loadfile_private</B>
|
|
|
|
are not included in this restriction.
|
|
<P>
|
|
The compilation units loaded by this function are added to the
|
|
"allowed units" list (see
|
|
<B>Dynlink.set_allowed_units</B>
|
|
|
|
).
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val loadfile_private </I>
|
|
|
|
:
|
|
<B>string -> unit</B>
|
|
|
|
<P>
|
|
Same as
|
|
<B>loadfile</B>
|
|
|
|
, except that the compilation units just loaded
|
|
are hidden (cannot be referenced) from other modules dynamically
|
|
loaded afterwards.
|
|
<P>
|
|
An exception will be raised if the given library defines toplevel
|
|
modules whose names clash with modules existing in either the main
|
|
program or a shared library previously loaded with
|
|
<B>loadfile</B>
|
|
|
|
.
|
|
Modules from shared libraries previously loaded with
|
|
<B>loadfile_private</B>
|
|
|
|
are not included in this restriction.
|
|
<P>
|
|
An exception will also be raised if the given library defines
|
|
toplevel modules whose name matches that of an interface depended
|
|
on by a module existing in either the main program or a shared
|
|
library previously loaded with
|
|
<B>loadfile</B>
|
|
|
|
. This applies even if
|
|
such dependency is only a "module alias" dependency (i.e. just on
|
|
the name rather than the contents of the interface).
|
|
<P>
|
|
The compilation units loaded by this function are not added to the
|
|
"allowed units" list (see
|
|
<B>Dynlink.set_allowed_units</B>
|
|
|
|
) since they cannot
|
|
be referenced from other compilation units.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val adapt_filename </I>
|
|
|
|
:
|
|
<B>string -> string</B>
|
|
|
|
<P>
|
|
In bytecode, the identity function. In native code, replace the last
|
|
extension with
|
|
<B>.cmxs</B>
|
|
|
|
.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAF"> </A>
|
|
<H3>Access control</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<P>
|
|
<I>val set_allowed_units </I>
|
|
|
|
:
|
|
<B>string list -> unit</B>
|
|
|
|
<P>
|
|
Set the list of compilation units that may be referenced from units that
|
|
are dynamically loaded in the future to be exactly the given value.
|
|
<P>
|
|
Initially all compilation units composing the program currently running
|
|
are available for reference from dynamically-linked units.
|
|
<B>set_allowed_units</B>
|
|
|
|
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.
|
|
<P>
|
|
Note that
|
|
<B>Dynlink.loadfile</B>
|
|
|
|
changes the allowed-units list.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val allow_only </I>
|
|
|
|
:
|
|
<B>string list -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>allow_only units</B>
|
|
|
|
sets the list of allowed units to be the intersection
|
|
of the existing allowed units and the given list of units. As such it
|
|
can never increase the set of allowed units.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val prohibit </I>
|
|
|
|
:
|
|
<B>string list -> unit</B>
|
|
|
|
<P>
|
|
<P>
|
|
<B>prohibit units</B>
|
|
|
|
prohibits dynamically-linked units from referencing
|
|
the units named in list
|
|
<B>units</B>
|
|
|
|
by removing such units from the allowed
|
|
units list. This can be used to prevent access to selected units,
|
|
e.g. private, internal modules of the running program.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val main_program_units </I>
|
|
|
|
:
|
|
<B>unit -> string list</B>
|
|
|
|
<P>
|
|
Return the list of compilation units that form the main program (i.e.
|
|
are not dynamically linked).
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val public_dynamically_loaded_units </I>
|
|
|
|
:
|
|
<B>unit -> string list</B>
|
|
|
|
<P>
|
|
Return the list of compilation units that have been dynamically loaded via
|
|
<B>loadfile</B>
|
|
|
|
(and not via
|
|
<B>loadfile_private</B>
|
|
|
|
). Note that compilation units
|
|
loaded dynamically cannot be unloaded.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val all_units </I>
|
|
|
|
:
|
|
<B>unit -> string list</B>
|
|
|
|
<P>
|
|
Return the list of compilation units that form the main program together
|
|
with those that have been dynamically loaded via
|
|
<B>loadfile</B>
|
|
|
|
(and not via
|
|
<B>loadfile_private</B>
|
|
|
|
).
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val allow_unsafe_modules </I>
|
|
|
|
:
|
|
<B>bool -> unit</B>
|
|
|
|
<P>
|
|
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.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<A NAME="lbAG"> </A>
|
|
<H3>Error reporting</H3>
|
|
|
|
<P>
|
|
<P>
|
|
|
|
<I>type linking_error </I>
|
|
|
|
= private
|
|
<BR> | Undefined_global
|
|
<B>of </B>
|
|
|
|
<B>string</B>
|
|
|
|
<BR> | Unavailable_primitive
|
|
<B>of </B>
|
|
|
|
<B>string</B>
|
|
|
|
<BR> | Uninitialized_global
|
|
<B>of </B>
|
|
|
|
<B>string</B>
|
|
|
|
<BR>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>type error </I>
|
|
|
|
= private
|
|
<BR> | Not_a_bytecode_file
|
|
<B>of </B>
|
|
|
|
<B>string</B>
|
|
|
|
<BR> | Inconsistent_import
|
|
<B>of </B>
|
|
|
|
<B>string</B>
|
|
|
|
<BR> | Unavailable_unit
|
|
<B>of </B>
|
|
|
|
<B>string</B>
|
|
|
|
<BR> | Unsafe_file
|
|
<BR> | Linking_error
|
|
<B>of </B>
|
|
|
|
<B>string * linking_error</B>
|
|
|
|
<BR> | Corrupted_interface
|
|
<B>of </B>
|
|
|
|
<B>string</B>
|
|
|
|
<BR> | Cannot_open_dynamic_library
|
|
<B>of </B>
|
|
|
|
<B>exn</B>
|
|
|
|
<BR> | Library's_module_initializers_failed
|
|
<B>of </B>
|
|
|
|
<B>exn</B>
|
|
|
|
<BR> | Inconsistent_implementation
|
|
<B>of </B>
|
|
|
|
<B>string</B>
|
|
|
|
<BR> | Module_already_loaded
|
|
<B>of </B>
|
|
|
|
<B>string</B>
|
|
|
|
<BR> | Private_library_cannot_implement_interface
|
|
<B>of </B>
|
|
|
|
<B>string</B>
|
|
|
|
<BR>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>exception Error </I>
|
|
|
|
<B>of </B>
|
|
|
|
<B>error</B>
|
|
|
|
<P>
|
|
<P>
|
|
Errors in dynamic linking are reported by raising the
|
|
<B>Error</B>
|
|
|
|
exception with a description of the error.
|
|
A common case is the dynamic library not being found on the system: this
|
|
is reported via
|
|
<B>Cannot_open_dynamic_library</B>
|
|
|
|
(the enclosed exception may
|
|
be platform-specific).
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<I>val error_message </I>
|
|
|
|
:
|
|
<B>error -> string</B>
|
|
|
|
<P>
|
|
Convert an error description to a printable message.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="1"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="2"><A HREF="#lbAC">Module</A><DD>
|
|
<DT id="3"><A HREF="#lbAD">Documentation</A><DD>
|
|
<DL>
|
|
<DT id="4"><A HREF="#lbAE">Dynamic loading of compiled files</A><DD>
|
|
<DT id="5"><A HREF="#lbAF">Access control</A><DD>
|
|
<DT id="6"><A HREF="#lbAG">Error reporting</A><DD>
|
|
</DL>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:39 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|