1% File src/library/base/man/library.dynam.Rd
2% Part of the R package, https://www.R-project.org
3% Copyright 1995-2017 R Core Team
4% Distributed under GPL 2 or later
5
6\name{library.dynam}
7\alias{library.dynam}
8\alias{library.dynam.unload}
9\alias{.dynLibs}
10\title{Loading DLLs from Packages}
11\description{
12  Load the specified file of compiled code if it has not been loaded
13  already, or unloads it.
14}
15\usage{
16library.dynam(chname, package, lib.loc,
17              verbose = getOption("verbose"),
18              file.ext = .Platform$dynlib.ext, \dots)
19
20library.dynam.unload(chname, libpath,
21                     verbose = getOption("verbose"),
22                     file.ext = .Platform$dynlib.ext)
23
24.dynLibs(new)
25}
26\arguments{
27  \item{chname}{a character string naming a DLL (also known as a dynamic
28    shared object or library) to load.}
29  \item{package}{a character vector with the name of package.}
30  \item{lib.loc}{a character vector describing the location of \R
31    library trees to search through.}
32  \item{libpath}{the path to the loaded package whose DLL is to be unloaded.}
33  \item{verbose}{a logical value indicating whether an announcement
34    is printed on the console before loading the DLL.  The
35    default value is taken from the verbose entry in the system
36    \code{\link{options}}.}
37  \item{file.ext}{the extension (including \samp{.} if used) to append
38    to the file name to specify the library to be loaded.  This defaults
39    to the appropriate value for the operating system.}
40  \item{\dots}{additional arguments needed by some libraries that
41    are passed to the call to \code{\link{dyn.load}} to control
42    how the library and its dependencies are loaded.}
43  \item{new}{a list of \code{"DLLInfo"} objects corresponding to the
44    DLLs loaded by packages.  Can be missing.}
45}
46\details{
47  See \code{\link{dyn.load}} for what sort of objects these functions handle.
48
49  \code{library.dynam} is designed to be used inside a package rather
50  than at the command line, and should really only be used inside
51  \code{\link{.onLoad}}.  The system-specific extension for DLLs (e.g.,
52  \file{.so} or \file{.sl} on Unix-alike systems,
53  \file{.dll} on Windows) should not be added.
54#ifdef windows
55
56  If \code{\dots} does not include a named argument \code{DLLpath},
57  \code{\link{dyn.load}} is called with \code{DLLpath} set to the
58  package's \file{libs} directory.  See the \dQuote{Windows} section of
59  the help on \code{\link{dyn.load}} for how to control where dependent
60  DLLs are found.
61
62  See \code{\link{dyn.load}} for comments about diagnostic messages
63  which may be seen on Windows.
64#endif
65
66  \code{library.dynam.unload} is designed for use in
67  \code{\link{.onUnload}}: it unloads the DLL and updates the value of
68  \code{.dynLibs()}
69
70  \code{.dynLibs} is used for getting (with no argument) or setting the
71  DLLs which are currently loaded by packages (using \code{library.dynam}).
72}
73\value{
74   If \code{chname} is not specified, \code{library.dynam} returns an
75  object of class \code{"\link{DLLInfoList}"} corresponding to the DLLs
76  loaded by packages.
77
78  If \code{chname} is specified, an object of class
79  \code{"\link{DLLInfo}"} that identifies the DLL and which can be used
80  in future calls is returned invisibly.  Note that the class
81  \code{"\link{DLLInfo}"} has a method for \code{$} which can be used to
82  resolve native symbols within that DLL.
83
84  \code{library.dynam.unload} invisibly returns an object of class
85  \code{"\link{DLLInfo}"} identifying the DLL successfully unloaded.
86
87  \code{.dynLibs} returns an object of class \code{"\link{DLLInfoList}"}
88  corresponding corresponding to its current value.
89}
90\section{Warning}{
91  Do not use \code{\link{dyn.unload}} on a DLL loaded by
92  \code{library.dynam}: use \code{library.dynam.unload} to ensure
93  that \code{.dynLibs} gets updated.  Otherwise a subsequent call to
94  \code{library.dynam} will be told the object is already loaded.
95
96  Note that whether or not it is possible to unload a DLL and then
97  reload a revised version of the same file is OS-dependent: see the
98  \sQuote{Value} section of the help for  \code{\link{dyn.unload}}.
99}
100\seealso{
101  \code{\link{getLoadedDLLs}} for information on \code{"DLLInfo"} and
102  \code{"DLLInfoList"} objects.
103
104  \code{\link{.onLoad}}, \code{\link{library}},
105  \code{\link{dyn.load}}, \code{\link{.packages}},
106  \code{\link{.libPaths}}
107
108  \code{\link{SHLIB}} for how to create suitable DLLs.
109}
110\references{
111  Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988)
112  \emph{The New S Language}.
113  Wadsworth & Brooks/Cole.
114}
115\examples{
116## Which DLLs were dynamically loaded by packages?
117library.dynam()
118
119## More on library.dynam.unload() :
120\donttest{require(nlme)
121nlme:::.onUnload # shows library.dynam.unload() call
122detach("package:nlme")  # by default, unload=FALSE ,  so,
123tail(library.dynam(), 2)# nlme still there
124
125## How to unload the DLL ?
126## Best is to unload the namespace,  unloadNamespace("nlme")
127## If we need to do it separately which should be exceptional:
128pd.file <- attr(packageDescription("nlme"), "file")
129library.dynam.unload("nlme", libpath = sub("/Meta.*", '', pd.file))
130tail(library.dynam(), 2)# 'nlme' is gone now
131unloadNamespace("nlme") # now gives warning
132}
133}
134\keyword{data}
135