| 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 = "", type = "")
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. 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. |
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". |
See
‘See Also’ and the Writing R Extensions and
R Installation and Administration manuals for how to
create and install
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 you should override them only if
there is good reason and you understand the implications.
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
some exceptions. 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 warn.FPU
is set to TRUE using the options function,
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.)
The function dyn.load is used for its side effect which links
the specified shared library 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 shared library.
is.loaded checks if the symbol name is loaded and hence
available for use in .C or .Fortran or .Call or
.Exernal: it requires the name you would give to .C etc
and not (as in S) that remapped by deprecated functions
symbol.C or symbol.For. It will succeed
if any one of the four calling functions would succeed in using the
entry point unless type is specified: for Fortran entry points
is.loaded(symbol.For("symbol")) will also succeed unless
the registration mechanism has been used.
Do not use dyn.unload on a shared object loaded by
library.dynam: use library.dynam.unload.
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 DLLs.
.C,
.Fortran,
.External,
.Call.
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")