\HeaderA{dyn.load}{Foreign Function Interface}{dyn.load}
\aliasA{dyn.unload}{dyn.load}{dyn.unload}
\aliasA{is.loaded}{dyn.load}{is.loaded}
\keyword{interface}{dyn.load}
\begin{Description}\relax
Load or unload DLLs (also known as shared objects), and test whether a
C function or Fortran subroutine is available.
\end{Description}
\begin{Usage}
\begin{verbatim}
dyn.load(x, local = TRUE, now = TRUE, ...)
dyn.unload(x)

is.loaded(symbol, PACKAGE = "", type = "")
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{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[\code{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.

\item[\code{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.

\item[\code{...}] other arguments for future expansion.

\item[\code{symbol}] a character string giving a symbol name.
\item[\code{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.  Use
\code{PACKAGE="base"} for symbols linked in to \R.  This is used in the
same way as in \code{\LinkA{.C}{.C}}, \code{\LinkA{.Call}{.Call}},
\code{\LinkA{.Fortran}{.Fortran}} and \code{\LinkA{.External}{.External}} functions
\item[\code{type}] The type of symbol to look for: can be any (\code{""}, the
default), \code{"Fortran"}, \code{"Call"} or \code{"External"}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
The objects \code{dyn.load} loads are called \sQuote{dynamically
loadable libraries} (abbreviated to \sQuote{DLL} on all platforms
except Mac OS X, which unfortunately uses the term for a different
sort of sobject.  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 \emph{Writing R Extensions} and \emph{R
Installation and Administration} manuals for how to create and install
a suitable DLL.  Note that unlike some versions of S-PLUS,
\code{dyn.load} does not load an object (\file{.o}) file but a shared
object or 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
defaults values are appropriate and you should override them only if
there is good reason and you understand the implications.

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 name space 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 and unsaved session variables will be lost.  The intended
use is for library developers to call specify a value \code{TRUE} to
check that all symbols are actually resolved and for regular users to
all 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 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{\LinkA{options}{options}} function.  Currently, we know of only 2
platforms that do not provide a value for local load (RTLD\_LOCAL).
These are IRIX6.4 and unpatched versions of Solaris 2.5.1.

There is a short discussion of these additional arguments with some
example code available at
\url{http://cm.bell-labs.com/stat/duncan/R/dynload}.
\end{Details}
\begin{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{\LinkA{getLoadedDLLs}{getLoadedDLLs}} for information about
this class.

The function \code{dyn.unload} unlinks the DLL.

\code{is.loaded} checks if the symbol name is loaded and hence
available for use 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{\LinkA{.Fortran}{.Fortran}} for how Fortran symbols are
mapped.)
\end{Value}
\begin{Section}{Warning}
Do not use \code{dyn.unload} on a DLL loaded by
\code{\LinkA{library.dynam}{library.dynam}}: use \code{\LinkA{library.dynam.unload}{library.dynam.unload}}.
This is needed for system houskeeping.
\end{Section}
\begin{Note}\relax
\code{is.loaded} requires the name you would give to \code{.C} etc
and \strong{not} (as in S) that remapped by defunct functions
\code{symbol.C} or \code{symbol.For}.

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.  The compatibility code for HP-UX was provided by
Luke Tierney.
\end{Note}
\begin{References}\relax
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
\emph{The New S Language}.
Wadsworth \& Brooks/Cole.
\end{References}
\begin{SeeAlso}\relax
\code{\LinkA{library.dynam}{library.dynam}} to be used inside a package's
\code{\LinkA{.First.lib}{.First.lib}} initialization.

\code{\LinkA{SHLIB}{SHLIB}} for how to create suitable DLLs.

\code{\LinkA{.C}{.C}},
\code{\LinkA{.Fortran}{.Fortran}},
\code{\LinkA{.External}{.External}},
\code{\LinkA{.Call}{.Call}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
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")
\end{ExampleCode}
\end{Examples}

