otherlibs/dynlink/dynlink.mli

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