| % File src/library/base/man/dynload.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2018 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{dyn.load} |
| \alias{dyn.load} |
| \alias{dyn.unload} |
| \alias{is.loaded} |
| \alias{R_MAX_NUM_DLLS} |
| #ifdef windows |
| \alias{DLLpath} |
| #endif |
| \title{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{ |
| \item{x}{a character string giving the pathname to a DLL, also known |
| as a dynamic shared object. (See \sQuote{Details} for what these |
| terms mean.)} |
| \item{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. |
| #ifdef windows |
| It is ignored on Windows. |
| #endif |
| } |
| \item{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. |
| #ifdef windows |
| It is ignored on Windows. |
| #endif |
| } |
| \item{\dots}{other arguments for future expansion. |
| #ifdef windows |
| See section \sQuote{Windows} below. |
| #endif |
| } |
| \item{symbol}{a character string giving a symbol name.} |
| \item{PACKAGE}{if supplied, confine the search for the \code{name} to |
| the DLL given by this argument (plus the conventional extension, |
| \file{.so}, \file{.sl}, \file{.dll}, \dots). 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 \code{\link{.C}}, \code{\link{.Call}}, |
| \code{\link{.Fortran}} and \code{\link{.External}} functions.} |
| \item{type}{The type of symbol to look for: can be any (\code{""}, the |
| default), \code{"Fortran"}, \code{"Call"} or \code{"External"}.} |
| } |
| \details{ |
| The objects \code{dyn.load} loads are called \sQuote{dynamically |
| loadable libraries} (abbreviated to \sQuote{DLL}) on all platforms |
| except macOS, which uses the term for a different sort |
| of object. On Unix-alikes they are also called \sQuote{dynamic |
| shared objects} (\sQuote{DSO}), or \sQuote{shared objects} for |
| short. (The POSIX standards use \sQuote{executable object file}, |
| but no one else does.) |
| |
| See \sQuote{See Also} and the \sQuote{Writing R Extensions} and |
| \sQuote{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 \code{PACKAGE} argument correctly, and may incorrectly find |
| symbols linked into \R. |
| |
| The additional arguments to \code{dyn.load} mirror the different |
| aspects of the mode argument to the \code{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. |
| |
| #ifdef unix |
| The \code{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 \sQuote{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 \code{now} argument as \code{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 \code{TRUE} to check that all symbols are actually resolved and |
| for regular users to call with \code{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 \code{_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 \code{verbose} or \code{warn} to be non-zero via the |
| \code{\link{options}} function. |
| |
| There is a short discussion of these additional arguments with some |
| example code available at |
| \url{http://www.stat.ucdavis.edu/~duncan/R/dynload/}. |
| #endif |
| #ifdef 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 |
| some exceptions. \code{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 \code{warn.FPU} |
| is set to \code{TRUE} using the \code{\link{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.) |
| #endif |
| } |
| \value{ |
| The function \code{dyn.load} is used for its side effect which links |
| the specified DLL to the executing \R image. Calls to \code{.C}, |
| \code{.Call}, \code{.Fortran} and \code{.External} can then be used to |
| execute compiled C functions or Fortran subroutines contained in the |
| library. The return value of \code{dyn.load} is an object of class |
| \code{DLLInfo}. See \code{\link{getLoadedDLLs}} for information about |
| this class. |
| |
| The function \code{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 uses 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. |
| |
| \code{is.loaded} checks if the symbol name is loaded \emph{and |
| searchable} and hence available for use as a character string value |
| for argument \code{.NAME} in \code{.C} or \code{.Fortran} or |
| \code{.Call} or \code{.External}. It will succeed if any one of the |
| four calling functions would succeed in using the entry point unless |
| \code{type} is specified. (See \code{\link{.Fortran}} for how Fortran |
| symbols are mapped.) Note that symbols in base packages are not |
| searchable, and other packages can be so marked. |
| } |
| \note{ |
| \code{is.loaded} requires the name you would give to \code{.C} etc |
| and \strong{not} (as in S) that remapped by the defunct functions |
| \code{symbol.C} or \code{symbol.For}. |
| |
| 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 \emph{via} the environment variable |
| \env{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 \command{ulimit -n} (\command{sh}, |
| \command{bash}) or \command{limit descriptors} (\command{csh}) in the |
| shell used to launch \R{}. Increasing \env{R_MAX_NUM_DLLS} comes with |
| some memory overhead. |
| |
| If the OS limit on the number of open files cannot be determined, the |
| DLL limit is 100 and cannot be changed \emph{via} \env{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 |
| \code{dlopen} has become the POSIX standard for doing this. Under |
| Unix-alikes \code{dyn.load} uses the \code{dlopen} mechanism and |
| should work on all platforms which support it. On Windows it uses the |
| standard mechanism (\code{LoadLibrary}) for loading DLLs. |
| |
| The original code for loading DLLs in Unix-alikes was provided by |
| Heiner Schwarte. |
| } |
| #ifdef windows |
| \section{Windows}{ |
| The \sQuote{standard mechanisms for loading DLLs} include a |
| search order for where a DLL is found (if not given as an absolute |
| path, which is preferred), \emph{and} of where its dependent DLLs will |
| be found. This search path depends on the version of Windows and its |
| security settings, but for versions since Windows XP SP1 it is |
| \itemize{ |
| \item The directory from which the application was launched. |
| \item The various system directories, |
| e.g.\sspace{}\file{c:/Windows/system32}, \file{c:/Windows/system} and |
| \file{c:/Windows}. |
| \item The current directory. |
| \item Along the search path for executables given by the environment |
| variable \env{PATH}. |
| } |
| |
| Packages often want to supply dependent DLLs in their \file{libs} |
| directory, and do this by setting the \env{PATH} variable |
| (\code{\link{library.dynam}} does 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 \code{DLLpath} is supplied to \code{dyn.load}, the latter |
| makes use of the Windows system call \code{SetDllDirectory} to insert |
| the value of \code{DLLpath} in second place, and removes the current |
| directory, for the duration of that \code{dyn.load} call. (Note that |
| only one directory can be inserted in this way.) |
| |
| Users have been confused by messages like |
| \preformatted{ |
| 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 \sQuote{module} |
| that could not be found is not \file{rJava.dll} but something else |
| Windows is looking for (here most likely Java DLLs): if you are lucky |
| there will be a dialog box with more details. |
| } |
| #endif |
| \section{Warning}{ |
| Do not use \code{dyn.unload} on a DLL loaded by |
| \code{\link{library.dynam}}: use \code{\link{library.dynam.unload}}. |
| This is needed for system housekeeping. |
| } |
| \references{ |
| Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) |
| \emph{The New S Language}. |
| Wadsworth & Brooks/Cole. |
| } |
| \seealso{ |
| \code{\link{library.dynam}} to be used inside a package's |
| \code{\link{.onLoad}} initialization. |
| |
| \code{\link{SHLIB}} for how to create suitable DLLs. |
| |
| \code{\link{.C}}, |
| \code{\link{.Fortran}}, |
| \code{\link{.External}}, |
| \code{\link{.Call}}. |
| } |
| \examples{ |
| ## 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 |
| } |
| \keyword{interface} |