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 DLLs (also known as shared objects), 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 = "")

_A_r_g_u_m_e_n_t_s:

       x: a character string giving the pathname to a DLL, also known
          as a dynamic shared object. (See 'Details' for what these
          terms mean.)

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

     ...: other arguments for future expansion. 

  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

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

_D_e_t_a_i_l_s:

     The objects 'dyn.load' loads are called 'dynamically loadable
     libraries' (abbreviated to 'DLL' on all platforms except Mac OS X,
     which unfortunately uses the term for a different sort of sobject.
      On Unix-alikes they are also called 'dynamic shared objects'
     ('DSO'), or 'shared objects' for short.  (The POSIX standards use
     'executable object file', but no one else does.)

     See 'See Also' and the 'Writing R Extensions' and 'R Installation
     and Administration' manuals for how to create and install a
     suitable DLL.

     Unfortunately a very few platforms (e.g. 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 POSIX
     systems. They are available so that users can exercise greater
     control over the loading process for an individual library.  In
     general, the default 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 name space 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.
      The intended use is for library developers to call with value
     'TRUE' to check that all symbols are actually resolved and for
     regular users to call 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 (very old) 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.

     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 DLL 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 DLL.  Note that unloading a
     DLL and then re-loading a DLL of the same name may or may not
     work: on Solaris it uses the first version loaded.

     'is.loaded' checks if the symbol name is loaded and hence
     available for use in '.C' or '.Fortran' or '.Call' or '.External'.
      It will succeed if any one of the four calling functions would
     succeed in using the entry point unless 'type' is specified.  (See
     '.Fortran' for how Fortran symbols are mapped.)

_W_a_r_n_i_n_g:

     Do not use 'dyn.unload' on a DLL loaded by 'library.dynam': use
     'library.dynam.unload'. This is needed for system houskeeping.

_N_o_t_e:

     'is.loaded' requires the name you would give to '.C' etc and *not*
     (as in S) that remapped by defunct functions 'symbol.C' or
     'symbol.For'.

     The creation of DLLs 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 POSIX standard for doing
     this. Under Unix-alikes 'dyn.load' uses the 'dlopen' mechanism and
     should work on all platforms which support it.  On Windows it uses
     the standard mechanism ('LoadLibrary') for loading DLLs.

     The original code for loading DLLs in Unix-alikes was provided by
     Heiner Schwarte.

_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 DLLs.

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