dyn.load                package:base                R Documentation

Foreign Function Interface

Description:

     Load or unload DLLs (also known as shared objects), and test
     whether a C function or Fortran subroutine is available.

Usage:

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

     is.loaded(symbol, PACKAGE = "", type = "")

Arguments:

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

Details:

     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.  Note that unlike some versions of S-PLUS,
     'dyn.load' does not load an object ('.o') file but a shared object
     or 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 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 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
     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>.

Value:

     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.

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

Warning:

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

Note:

     '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.  The compatibility code for HP-UX was provided by
     Luke Tierney.

References:

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

See Also:

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

     'SHLIB' for how to create suitable DLLs.

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

Examples:

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

