| % File src/library/base/man/library.dynam.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2017 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{library.dynam} |
| \alias{library.dynam} |
| \alias{library.dynam.unload} |
| \alias{.dynLibs} |
| \title{Loading DLLs from Packages} |
| \description{ |
| Load the specified file of compiled code if it has not been loaded |
| already, or unloads it. |
| } |
| \usage{ |
| library.dynam(chname, package, lib.loc, |
| verbose = getOption("verbose"), |
| file.ext = .Platform$dynlib.ext, \dots) |
| |
| library.dynam.unload(chname, libpath, |
| verbose = getOption("verbose"), |
| file.ext = .Platform$dynlib.ext) |
| |
| .dynLibs(new) |
| } |
| \arguments{ |
| \item{chname}{a character string naming a DLL (also known as a dynamic |
| shared object or library) to load.} |
| \item{package}{a character vector with the name of package.} |
| \item{lib.loc}{a character vector describing the location of \R |
| library trees to search through.} |
| \item{libpath}{the path to the loaded package whose DLL is to be unloaded.} |
| \item{verbose}{a logical value indicating whether an announcement |
| is printed on the console before loading the DLL. The |
| default value is taken from the verbose entry in the system |
| \code{\link{options}}.} |
| \item{file.ext}{the extension (including \samp{.} if used) to append |
| to the file name to specify the library to be loaded. This defaults |
| to the appropriate value for the operating system.} |
| \item{\dots}{additional arguments needed by some libraries that |
| are passed to the call to \code{\link{dyn.load}} to control |
| how the library and its dependencies are loaded.} |
| \item{new}{a list of \code{"DLLInfo"} objects corresponding to the |
| DLLs loaded by packages. Can be missing.} |
| } |
| \details{ |
| See \code{\link{dyn.load}} for what sort of objects these functions handle. |
| |
| \code{library.dynam} is designed to be used inside a package rather |
| than at the command line, and should really only be used inside |
| \code{\link{.onLoad}}. The system-specific extension for DLLs (e.g., |
| \file{.so} or \file{.sl} on Unix-alike systems, |
| \file{.dll} on Windows) should not be added. |
| #ifdef windows |
| |
| If \code{\dots} does not include a named argument \code{DLLpath}, |
| \code{\link{dyn.load}} is called with \code{DLLpath} set to the |
| package's \file{libs} directory. See the \dQuote{Windows} section of |
| the help on \code{\link{dyn.load}} for how to control where dependent |
| DLLs are found. |
| |
| See \code{\link{dyn.load}} for comments about diagnostic messages |
| which may be seen on Windows. |
| #endif |
| |
| \code{library.dynam.unload} is designed for use in |
| \code{\link{.onUnload}}: it unloads the DLL and updates the value of |
| \code{.dynLibs()} |
| |
| \code{.dynLibs} is used for getting (with no argument) or setting the |
| DLLs which are currently loaded by packages (using \code{library.dynam}). |
| } |
| \value{ |
| If \code{chname} is not specified, \code{library.dynam} returns an |
| object of class \code{"\link{DLLInfoList}"} corresponding to the DLLs |
| loaded by packages. |
| |
| If \code{chname} is specified, an object of class |
| \code{"\link{DLLInfo}"} that identifies the DLL and which can be used |
| in future calls is returned invisibly. Note that the class |
| \code{"\link{DLLInfo}"} has a method for \code{$} which can be used to |
| resolve native symbols within that DLL. |
| |
| \code{library.dynam.unload} invisibly returns an object of class |
| \code{"\link{DLLInfo}"} identifying the DLL successfully unloaded. |
| |
| \code{.dynLibs} returns an object of class \code{"\link{DLLInfoList}"} |
| corresponding corresponding to its current value. |
| } |
| \section{Warning}{ |
| Do not use \code{\link{dyn.unload}} on a DLL loaded by |
| \code{library.dynam}: use \code{library.dynam.unload} to ensure |
| that \code{.dynLibs} gets updated. Otherwise a subsequent call to |
| \code{library.dynam} will be told the object is already loaded. |
| |
| Note that whether or not it is possible to unload a DLL and then |
| reload a revised version of the same file is OS-dependent: see the |
| \sQuote{Value} section of the help for \code{\link{dyn.unload}}. |
| } |
| \seealso{ |
| \code{\link{getLoadedDLLs}} for information on \code{"DLLInfo"} and |
| \code{"DLLInfoList"} objects. |
| |
| \code{\link{.onLoad}}, \code{\link{library}}, |
| \code{\link{dyn.load}}, \code{\link{.packages}}, |
| \code{\link{.libPaths}} |
| |
| \code{\link{SHLIB}} for how to create suitable DLLs. |
| } |
| \references{ |
| Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) |
| \emph{The New S Language}. |
| Wadsworth & Brooks/Cole. |
| } |
| \examples{ |
| ## Which DLLs were dynamically loaded by packages? |
| library.dynam() |
| |
| ## More on library.dynam.unload() : |
| \donttest{require(nlme) |
| nlme:::.onUnload # shows library.dynam.unload() call |
| detach("package:nlme") # by default, unload=FALSE , so, |
| tail(library.dynam(), 2)# nlme still there |
| |
| ## How to unload the DLL ? |
| ## Best is to unload the namespace, unloadNamespace("nlme") |
| ## If we need to do it separately which should be exceptional: |
| pd.file <- attr(packageDescription("nlme"), "file") |
| library.dynam.unload("nlme", libpath = sub("/Meta.*", '', pd.file)) |
| tail(library.dynam(), 2)# 'nlme' is gone now |
| unloadNamespace("nlme") # now gives warning |
| } |
| } |
| \keyword{data} |