dyn.load {base}R Documentation

Foreign Function Interface

Description

Load or unload shared libraries, 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)
symbol.C(name)
symbol.For(name)

Arguments

x 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 system-dependent. It is ignored on Windows.
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. It is ignored on Windows.
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).

Details

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 one should override them only if there is good reason and you understand the implications.

Value

The function dyn.load is used for its side effect which links the specified shared library to the executing 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 or subroutine names to the symbol name in the compiled code: is.loaded checks if the symbol name is loaded and hence available for use in .C or .Fortran.

Note

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.

See Also

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

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

Examples

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