dyn.load                package: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

_D_e_s_c_r_i_p_t_i_o_n:

     Load or unload shared libraries, and test whether a C function or
     Fortran subroutine is available.

_U_s_a_g_e:

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

     is.loaded(symbol, PACKAGE = "", type = "")
     symbol.C(name)
     symbol.For(name)

_A_r_g_u_m_e_n_t_s:

       x: a character string giving the pathname to a shared library or
          DLL.

   local: a logical value controlling whether the symbols in the shared
          library are stored in their own local table and not shared
          across shared libraries, or added to the global symbol table.
           Whether this has any effect is system-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 symbols, and for users to ignore missing symbols.
          Whether this has any effect is system-dependent. 

  symbol: a character string giving a symbol name.

 PACKAGE: if supplied, confine the search for the 'name' to the DLL
          given by this argument (plus the conventional extension,
          '.so', '.sl', '.dll', ...).  This is intended to add safety
          for packages, which can ensure by using this argument that no
          other package can override their external symbols.  Use
          'PACKAGE="base"' for symbols linked in to R.  This is used in
          the same way as in '.C', '.Call', '.Fortran' and '.External'
          functions

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

    type: The type of symbol to look for: can be any ('""', the
          default), '"Fortran"', '"Call"' or '"External"'.

_D_e_t_a_i_l_s:

     See 'See Also' and the _Writing R Extensions_ and _R Installation
     and Administration_ manuals for how to create and install  a
     suitable shared library.  Note that unlike some versions of
     S-PLUS, 'dyn.load' does not load an object ('.o') file but a
     shared library or DLL.

     Unfortunately a very few platforms (Compaq Tru64) do not handle
     the 'PACKAGE' argument correctly, and may incorrectly find symbols
     linked into R.

     The additional arguments to 'dyn.load' mirror the different
     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 you 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 symbols 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 platforms 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 arguments with
     some example code available at <URL:
     http://cm.bell-labs.com/stat/duncan/R/dynload>.

_V_a_l_u_e:

     The function 'dyn.load' is used for its side effect which links
     the specified shared library to the executing R image.  Calls to
     '.C', '.Call', '.Fortran' and '.External' can then be used to
     execute compiled C functions or Fortran subroutines contained in
     the library. The return value of 'dyn.load' is an object of class
     'DLLInfo'. See 'getLoadedDLLs' for information about this class.

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

     Functions 'symbol.C' and 'symbol.For' are for historical
     compatibility with S.  'symbol.C' just returns its argument
     unchanged, whereas 'symbol.For' will append an underscore on those
     platforms (almost all) which do so for Fortran symbols. These are
     no longer of much use in R.

     'is.loaded' checks if the symbol name is loaded and hence
     available for use in '.C' or '.Fortran' or '.Call' or '.Exernal':
     it requires the name you would give to '.C' etc and *not* that
     remapped by 'symbol.C' or 'symbol.For'.  It will succeed if any
     one of the four calling functions would succeed in using the entry
     point unless 'type' is specified: for Fortran entry points
     'is.loaded(symbol.For("symbol"))' will also succeed _unless_ the
     registration mechanism has been used.

_W_a_r_n_i_n_g:

     Do not use 'dyn.unload' on a shared object loaded by
     'library.dynam': use 'library.dynam.unload'.

_N_o_t_e:

     The creation of shared libraries and the runtime linking of them
     into executing programs is very platform dependent.  In recent
     years there has been some simplification 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' mechanism
     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.

_R_e_f_e_r_e_n_c_e_s:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

_S_e_e _A_l_s_o:

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

     'SHLIB' for how to create suitable shared objects.

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

_E_x_a_m_p_l_e_s:

     is.loaded("hcass2") #-> probably TRUE, as stats is loaded
     is.loaded("supsmu") # Fortran entry point in stats
     is.loaded("supsmu", "stats", "Fortran")
     is.loaded("PDF", type = "External")

