| dyn.load {base} | R Documentation |
Foreign Function Interface
Description
Load or unload DLLs (also known as shared objects), 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, PACKAGE = "", type = "")
Arguments
x |
a character string giving the pathname to a DLL, also known as a dynamic shared object. (See ‘Details’ for what these terms mean.) |
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. |
now |
a logical controlling whether all symbols are resolved (and relocated) immediately when 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. |
... |
other arguments for future expansion. |
symbol |
a character string giving a symbol name. |
PACKAGE |
if supplied, confine the search for the |
type |
the type of symbol to look for: can be any ( |
Details
The objects dyn.load loads are called ‘dynamically
loadable libraries’ (abbreviated to ‘DLL’) on all platforms
except macOS, 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 some rare platforms (e.g., 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 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.
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 one potential side-effect of using lazy
loading via now = 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 this with
value TRUE to check that all symbols are actually resolved and
for regular users to call it 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 (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
options verbose or warn to be non-zero via the
options function.
There is a short discussion of these additional arguments with some example code available at https://www.stat.ucdavis.edu/~duncan/R/dynload/.
Value
The function dyn.load is used for its side effect which links
the specified DLL 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 DLL. Note that unloading a
DLL and then re-loading a DLL of the same name may or may not work: on
Solaris it used the first version loaded. Note also that some DLLs cannot
be safely unloaded at all: unloading a DLL which implements C finalizers
but does not unregister them on unload causes R to crash.
is.loaded checks if the symbol name is loaded and
searchable and hence available for use as a character string value
for argument .NAME in .C, .Fortran,
.Call, or .External. It will succeed if any one of the
four calling functions would succeed in using the entry point unless
type is specified. (See .Fortran for how Fortran
symbols are mapped.) Note that symbols in base packages are not
searchable, and other packages can be so marked.
Warning
Do not use dyn.unload on a DLL loaded by
library.dynam: use library.dynam.unload.
This is needed for system housekeeping.
Note
is.loaded requires the name you would give to .C etc.
It must be a character string and so cannot be an R object as used
for registered native symbols (see “Writing R Extensions”
section 5.4.). Some registered symbols are available by name but most are
not, including those in the examples below.
By default, the maximum number of DLLs that can be loaded is now 614
when the OS limit on the number of open files allows or can be
increased, but less otherwise (but it will be at least 100). A
specific maximum can be requested via the environment variable
R_MAX_NUM_DLLS, which has to be set (to a value between 100 and
1000 inclusive) before starting an R session. If the OS limit on
the number of open files does not allow using this maximum and cannot
be increased, R will fail to start with an error. The maximum is not
allowed to be greater than 60% of the OS limit on the number of open
files (essentially unlimited on Windows, on Unix typically 1024, but
256 on macOS). The limit can sometimes (including on macOS) be
modified using command ulimit -n (sh,
bash) or limit descriptors (csh) in the
shell used to launch R. Increasing R_MAX_NUM_DLLS comes with
some memory overhead, and be aware that many types of
connections also use file descriptors.
If the OS limit on the number of open files cannot be determined, the DLL limit is 100 and cannot be changed via R_MAX_NUM_DLLS.
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
Unix-alikes 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.
References
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
See Also
library.dynam to be used inside a package's
.onLoad initialization.
SHLIB for how to create suitable DLLs.
.C,
.Fortran,
.External,
.Call.
Examples
## expect all of these to be false in R >= 3.0.0 as these can only be
## used via registered symbols.
is.loaded("supsmu") # Fortran entry point in stats
is.loaded("supsmu", "stats", "Fortran")
is.loaded("PDF", type = "External") # pdf() device in grDevices