dyn.load(x, local = TRUE, now = TRUE, ...) dyn.unload(x)
is.loaded(symbol, PACKAGE = "", type = "")
nameto the DLL given by this argument (plus the conventional extension,
.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 default),
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.
libsdirectory, and do this by setting the
library.dynamdoes that automatically in recent versions of R), but the DLL search order means that DLLs in the launch directory and in system directories will be preferred. On Windows XP SP1 and later there is a way to modify the search order. If argument
DLLpathis supplied to
dyn.load, the latter makes use of the Windows system call
SetDllDirectoryto insert the value of
DLLpathin second place, and removes the current directory, for the duration of that
dyn.loadcall. (Note that only one directory can be inserted in this way.) Users have been confused by messages like
error: unable to load shared object '.../library/rJava/libs/x64/rJava.dll': LoadLibrary failure: The specified module could not be found.The final line is a Windows (not R) diagnostic: the ‘module’ that could not be found is not
rJava.dllbut something else Windows is looking for (here most likely Java DLLs): if you are lucky there will be a dialog box with more details.
dyn.loadloads 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 a very few platforms (e.g., Compaq Tru64) do not handle the
PACKAGEargument correctly, and may incorrectly find symbols linked into R. The additional arguments to
dyn.loadmirror 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
localargument 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
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 value
TRUEto check that all symbols are actually resolved and for regular users to call with
FALSEso 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
warnto be non-zero via the
optionsfunction. There is a short discussion of these additional arguments with some example code available at http://www.stat.ucdavis.edu/~duncan/R/dynload/. 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.loaddetects 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.FPUis set to
optionsfunction, 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.)
library.dynamto be used inside a package's
SHLIBfor how to create suitable DLLs.