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