

dynload {base}                               R Documentation

_F_o_r_e_i_g_n _F_u_n_c_t_i_o_n _I_n_t_e_r_f_a_c_e

_U_s_a_g_e_:

     dyn.load(libname, local=TRUE, now=TRUE)
     dyn.unload(libname)

     is.loaded(symbol)
     symbol.C(name)
     symbol.For(name)

_A_r_g_u_m_e_n_t_s_:

 libname: a character string giving the pathname to a DLL.

   local: a logical value controlling whether the symbols in
          the DLL are stored in their own local table and
          not shared across DLLs, or added to the global
          symbol table. Whether this has any effect is sys-
          tem-dependent.

     now: a logical controlling whether all symbols are
          resolved (and relocated) immediately the library
          is loaded or deferred until they are used. This
          control is useful for developers testing whether a
          library is complete and has all the necessary sym-
          bols and for users to ignore missing symbols.

  symbol: a character string giving a symbol name.

    name: a character string giving either the name of a C
          function or Fortran subroutine. Fortran names
          probably need to be given entirely in lower case
          (but this may be system-dependent).

_V_a_l_u_e_:

     The function `dyn.load' is used for its side effect
     which links the specified shared library to the execut-
     ing R image.  Calls to `.C', `.Fortran' and `.External'
     can then be used to execute compiled C functions or
     Fortran subroutines contained in the library.

     The function `dyn.unload' unlinks the shared library.

     Functions `symbol.C' and `symbol.For' map function /
     subroutine names to the symbol name in the compiled
     code: `is.loaded' checks if the symbol name is loaded
     and so available for use in `.C' ....

     The additional arguments to `dyn.load' mirror the dif-
     ferent aspects of the mode argument to the dlopen()
     routine on UNIX systems. They are available so that
     users can exercise greater control over the loading
     process for an individual library. In general, the
     defaults values are appropriate and one should override
     them only if there is good reason and you understand
     the implications.

     The `local' argument allows one to control whether the
     symbols in the DLL being attached are visible to other
     DLLs.  While maintaining the symbols in their own
     namespace is good practice, the ability to share sym-
     bols across related ``chapters'' is useful in many
     cases.  Additionally, on certain platforms and versions
     of an operating system, certain libraries must have
     their symbols loaded globally to successfully resolve
     all symbols.

     One should be careful of the potential side-effect of
     using lazy loading via the `now' argument as `FALSE'.
     If a routine is called that has a missing symbol, the
     process will terminate immediately and unsaved session
     variables will be lost. The intended use is for library
     developers to call specify a value `TRUE' to check that
     all symbols are actually resolved and for regular users
     to all with `FALSE' so that missing symbols can be
     ignored and the available ones can be called.

     The initial motivation for adding these was to avoid
     such termination in the `_init()' routines of the Java
     virtual machine library. However, symbols loaded
     locally may not be (read probably) available to other
     DLLs. Those added to the global table are available to
     all other elements of the application and so can be
     shared across two different DLLs.

     Some systems do not provide (explicit) support for
     local/global and lazy/eager symbol resolution.  This
     can be the source of subtle bugs.  One can arrange to
     have warning messages emitted when unsupported options
     are used.  This is done by setting either of the
     options `verbose' or `warn' to be non-zero via the
     `options' function.  Currently, we know of only 2 plat-
     forms that do not provide a value for local load
     (RTLD_LOCAL).  These are IRIX6.4 and unpatched versions
     of Solaris 2.5.1.

     There is a short discussion of these additional argu-
     ments with some example code available at <URL:
     http://cm.bell-labs.com/stat/duncan/R/dynload>.

_N_o_t_e_:

     The creation of shared libraries and the runtime link-
     ing of them into executing programs is very platform
     dependent.  In recent years there has been some simpli-
     fication in the process because the C subroutine call
     `dlopen' has become the standard for doing this under
     UNIX.  Under UNIX `dyn.load' uses the `dlopen' mecha-
     nism and should work on all platforms which support it.
     On Windows it uses the standard mechanisms for loading
     32-bit DLLs.

     The original code for loading DLLs in UNIX was provided
     by Heiner Schwarte.  The compatibility code for HP-UX
     was provided by Luke Tierney.

_S_e_e _A_l_s_o_:

     `library.dynam' to be used inside a package's
     `.First.lib' initialization.

     `.C', `.Fortran', `.External', `.Call'.

_E_x_a_m_p_l_e_s_:

     is.loaded(symbol.For("hcass2")) #-> probably  FALSE
     library(mva)
     is.loaded(symbol.For("hcass2")) #-> TRUE

