1(**************************************************************************)
2(*                                                                        *)
3(*                                 OCaml                                  *)
4(*                                                                        *)
5(*             Xavier Leroy, projet Cristal, INRIA Rocquencourt           *)
6(*                                                                        *)
7(*   Copyright 1996 Institut National de Recherche en Informatique et     *)
8(*     en Automatique.                                                    *)
9(*                                                                        *)
10(*   All rights reserved.  This file is distributed under the terms of    *)
11(*   the GNU Lesser General Public License version 2.1, with the          *)
12(*   special exception on linking described in the file LICENSE.          *)
13(*                                                                        *)
14(**************************************************************************)
15
16(** Dynamic loading of object files. *)
17
18val is_native: bool
19(** [true] if the program is native,
20    [false] if the program is bytecode. *)
21
22(** {6 Dynamic loading of compiled files} *)
23
24val loadfile : string -> unit
25(** In bytecode: load the given bytecode object file ([.cmo] file) or
26    bytecode library file ([.cma] file), and link it with the running
27    program. In native code: load the given OCaml plugin file (usually
28    [.cmxs]), and link it with the running
29    program.
30    All toplevel expressions in the loaded compilation units
31    are evaluated. No facilities are provided to
32    access value names defined by the unit. Therefore, the unit
33    must register itself its entry points with the main program,
34    e.g. by modifying tables of functions. *)
35
36val loadfile_private : string -> unit
37(** Same as [loadfile], except that the compilation units just loaded
38    are hidden (cannot be referenced) from other modules dynamically
39    loaded afterwards. *)
40
41val adapt_filename : string -> string
42(** In bytecode, the identity function. In native code, replace the last
43    extension with [.cmxs]. *)
44
45(** {6 Access control} *)
46
47val allow_only: string list -> unit
48(** [allow_only units] restricts the compilation units that
49    dynamically-linked units can reference: it forbids all references
50    to units other than those named in the list [units]. References
51    to any other compilation unit will cause a [Unavailable_unit]
52    error during [loadfile] or [loadfile_private].
53
54    Initially (or after calling [default_available_units]) all
55    compilation units composing the program currently running are
56    available for reference from dynamically-linked units.
57    [allow_only] can be used to restrict access to a subset of these
58    units, e.g. to the units that compose the API for
59    dynamically-linked code, and prevent access to all other units,
60    e.g. private, internal modules of the running program. If
61    [allow_only] is called several times, access will be restricted to
62    the intersection of the given lists (i.e. a call to [allow_only]
63    can never increase the set of available units). *)
64
65val prohibit: string list -> unit
66(** [prohibit units] prohibits dynamically-linked units from referencing
67    the units named in list [units].  This can be used to prevent
68    access to selected units, e.g. private, internal modules of
69    the running program. *)
70
71val default_available_units: unit -> unit
72(** Reset the set of units that can be referenced from dynamically-linked
73    code to its default value, that is, all units composing the currently
74    running program. *)
75
76val allow_unsafe_modules : bool -> unit
77(** Govern whether unsafe object files are allowed to be
78    dynamically linked. A compilation unit is 'unsafe' if it contains
79    declarations of external functions, which can break type safety.
80    By default, dynamic linking of unsafe object files is
81    not allowed. In native code, this function does nothing; object files
82    with external functions are always allowed to be dynamically linked. *)
83
84(** {6 Deprecated, low-level API for access control} *)
85
86(** @deprecated  The functions [add_interfaces], [add_available_units]
87    and [clear_available_units] should not be used in new programs,
88    since the default initialization of allowed units, along with the
89    [allow_only] and [prohibit] function, provides a better, safer
90    mechanism to control access to program units.  The three functions
91    below are provided for backward compatibility only and are not
92    available in native code. *)
93
94val add_interfaces : string list -> string list -> unit
95(** [add_interfaces units path] grants dynamically-linked object
96    files access to the compilation  units named in list [units].
97    The interfaces ([.cmi] files) for these units are searched in
98    [path] (a list of directory names). *)
99
100val add_available_units : (string * Digest.t) list -> unit
101(** Same as {!Dynlink.add_interfaces}, but instead of searching [.cmi] files
102    to find the unit interfaces, uses the interface digests given
103    for each unit. This way, the [.cmi] interface files need not be
104    available at run-time. The digests can be extracted from [.cmi]
105    files using the [extract_crc] program installed in the
106    OCaml standard library directory. *)
107
108val clear_available_units : unit -> unit
109(** Empty the list of compilation units accessible to dynamically-linked
110    programs. *)
111
112(** {6 Deprecated, initialization} *)
113
114val init : unit -> unit
115(** @deprecated Initialize the [Dynlink] library. This function is called
116    automatically when needed. *)
117
118(** {6 Error reporting} *)
119
120type linking_error =
121    Undefined_global of string
122  | Unavailable_primitive of string
123  | Uninitialized_global of string
124
125type error =
126    Not_a_bytecode_file of string
127  | Inconsistent_import of string
128  | Unavailable_unit of string
129  | Unsafe_file
130  | Linking_error of string * linking_error
131  | Corrupted_interface of string
132  | File_not_found of string
133  | Cannot_open_dll of string
134  | Inconsistent_implementation of string
135
136exception Error of error
137(** Errors in dynamic linking are reported by raising the [Error]
138    exception with a description of the error. *)
139
140val error_message : error -> string
141(** Convert an error description to a printable message. *)
142
143
144(**/**)
145
146(** {6 Internal functions} *)
147
148val digest_interface : string -> string list -> Digest.t
149