| dyn.load {base} | R Documentation |
Load or unload shared libraries, and test whether a C function or Fortran subroutine is available.
dyn.load(x, local = TRUE, now = TRUE) dyn.unload(x) is.loaded(symbol, PACKAGE="") symbol.C(name) symbol.For(name)
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). |
See
‘See Also’ and the Writing R Extensions manual for how to
create 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 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 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 http://cm.bell-labs.com/stat/duncan/R/dynload.
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.
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.
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
library.dynam to be used inside a package's
.First.lib initialization.
SHLIB for how to create suitable shared objects.
.C,
.Fortran,
.External,
.Call.
is.loaded(symbol.For("hcass2")) #-> probably TRUE, as stats is loaded