

   dynload {base}                               R Documentation

   FFoorreeiiggnn FFuunnccttiioonn IInntteerrffaaccee

   UUssaaggee::

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

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

   AArrgguummeenntts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Vaalluue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Nootte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Seeee AAllssoo::

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

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

   EExxaammpplleess::

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

