Foreign Function Interface
Load or unload DLLs (also known as shared objects), 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 = "", type = "")
- a character string giving the pathname to a DLL, also known as a dynamic shared object. (See Details for what these terms mean.)
- 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. windows It is ignored on Windows.
- 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. windows It is ignored on Windows.
- other arguments for future expansion. windows See section Windows below.
- a character string giving a symbol name.
- if supplied, confine the search for the
nameto 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. This is used in the same way as in
- The type of symbol to look for: can be any (
"", the default),
dyn.load loads are called dynamically
loadable libraries (abbreviated to DLL) on all platforms
except OS X, which uses the term for a different sort
of object. 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
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.
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. The intended use is for library developers to call with
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
_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
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
warn to be non-zero via the
There is a short discussion of these additional arguments with some example code available at http://cm.bell-labs.com/stat/duncan/R/dynload. windows
External code must not change the floating point control word, but
many DLLs do so. Common changes are to set it to use 53 bit
precision instead of R's default 64 bit precision, or to unmask
dyn.load detects such changes,
and restores R's control word to its default value of hex 8001F.
This may cause the DLL to malfunction; if so, it should be rewritten
to save and restore the control word itself. If
is set to
TRUE using the
a warning will be printed. (If the warning says
that the control word was changed from some other value than 8001F,
please report the circumstances to the Windows maintainers:
that probably indicates an internal bug.)
dyn.loadis used for its side effect which links the specified DLL to the executing R image. Calls to
.Externalcan then be used to execute compiled C functions or Fortran subroutines contained in the library. The return value of
dyn.loadis an object of class
getLoadedDLLsfor information about this class.The function
dyn.unloadunlinks 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.loadedchecks if the symbol name is loaded and searchable and hence available for use as a character string value for argument
.External. It will succeed if any one of the four calling functions would succeed in using the entry point unless
typeis specified. (See
.Fortranfor how Fortran symbols are mapped.) Note that symbols in base packages are not searchable, and other packages can be so marked.
is.loaded requires the name you would give to
and not (as in S) that remapped by the defunct functions
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
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.
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
SHLIB for how to create suitable DLLs.
## expect all of these to be false in R >= 3.0.0. is.loaded("supsmu") # Fortran entry point in stats is.loaded("supsmu", "stats", "Fortran") is.loaded("PDF", type = "External") # pdf() device in grDevices