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