Dynlink - Dynamic loading of .cmo, .cma and .cmxs files.

       Module Dynlink
        : sigend

       Dynamic loading of .cmo, .cma and .cmxs files.

       valis_native : booltrue if the program is native, false if the program is bytecode.

   Dynamicloadingofcompiledfilesvalloadfile : string->unit

       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 itself register its  entry  points  with
       the main program (or a previously-loaded library) e.g. by modifying tables of functions.

       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 loadfile .   Modules  from
       shared libraries previously loaded with loadfile_private are not included in this restriction.

       The   compilation   units   loaded  by  this  function  are  added  to  the  "allowed  units"  list  (see
       Dynlink.set_allowed_units ).

       valloadfile_private : string->unit

       Same as loadfile , except that the compilation units just loaded are hidden (cannot be  referenced)  from
       other modules dynamically loaded afterwards.

       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 loadfile .   Modules  from
       shared libraries previously loaded with loadfile_private are not included in this restriction.

       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 loadfile . 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).

       The  compilation  units  loaded  by  this  function  are  not  added  to  the  "allowed  units" list (see
       Dynlink.set_allowed_units ) since they cannot be referenced from other compilation units.

       valadapt_filename : string->string

       In bytecode, the identity function. In native code, replace the last extension with .cmxs .

   Accesscontrolvalset_allowed_units : stringlist->unit

       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.

       Initially  all compilation units composing the program currently running are available for reference from
       dynamically-linked units.  set_allowed_units 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.

       Note that Dynlink.loadfile changes the allowed-units list.

       valallow_only : stringlist->unitallow_onlyunits 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.

       valprohibit : stringlist->unitprohibitunits  prohibits  dynamically-linked  units  from  referencing the units named in list units 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.

       valmain_program_units : unit->stringlist

       Return the list of compilation units that form the main program (i.e.  are not dynamically linked).

       valpublic_dynamically_loaded_units : unit->stringlist

       Return  the  list  of  compilation  units  that  have  been  dynamically loaded via loadfile (and not via
       loadfile_private ).  Note that compilation units loaded dynamically cannot be unloaded.

       valall_units : unit->stringlist

       Return the list of compilation units that form the main  program  together  with  those  that  have  been
       dynamically loaded via loadfile (and not via loadfile_private ).

       valallow_unsafe_modules : bool->unit

       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.

   Errorreportingtypelinking_error = private
        | Undefined_global ofstring
        | Unavailable_primitive ofstring
        | Uninitialized_global ofstringtypeerror = private
        | Not_a_bytecode_file ofstring
        | Inconsistent_import ofstring
        | Unavailable_unit ofstring
        | Unsafe_file
        | Linking_error ofstring*linking_error
        | Corrupted_interface ofstring
        | Cannot_open_dynamic_library ofexn
        | Library's_module_initializers_failed ofexn
        | Inconsistent_implementation ofstring
        | Module_already_loaded ofstring
        | Private_library_cannot_implement_interface ofstringexceptionErroroferror

       Errors in dynamic linking are reported by raising the Error exception with a description of the error.  A
       common  case  is  the  dynamic  library  not  being  found  on  the  system:   this   is   reported   via
       Cannot_open_dynamic_library (the enclosed exception may be platform-specific).

       valerror_message : error->string

       Convert an error description to a printable message.

OCamldoc                                           2025-06-12                                        Dynlink(3o)

       Module   Dynlink

       Dynlink - Dynamic loading of .cmo, .cma and .cmxs files.