|
0
|
1 \name{dynload}
|
|
|
2 \alias{dynload}
|
|
|
3 \alias{.dynload}
|
|
|
4 \alias{.dynunload}
|
|
|
5 \alias{.dynsym}
|
|
|
6 \title{Loading of shared libraries and resolving of symbols (Alternative Framework)}
|
|
|
7 \description{Alternative framework for loading of shared libraries and resolving of symbols.
|
|
|
8 The framework offers \emph{automatic unload management} of shared libraries and
|
|
|
9 provides a direct interface to the dynamic linker of the OS.
|
|
|
10 }
|
|
|
11 \usage{
|
|
|
12 .dynload(libname, auto.unload=TRUE)
|
|
|
13 .dynsym(libhandle, symname, protect.lib=TRUE)
|
|
|
14 .dynunload(libhandle)
|
|
|
15 }
|
|
|
16 \arguments{
|
|
|
17 \item{libname}{character string giving the pathname to a shared library in OS-specific notation.}
|
|
|
18 \item{libhandle}{external pointer representing a handle to an opened library.}
|
|
|
19 \item{symname}{character string specifying a symbolic name to be resolved.}
|
|
|
20 \item{auto.unload}{logical, if \code{TRUE} a finalizer will be registered that will automatically unload the library.}
|
|
|
21 \item{protect.lib}{logical, if \code{TRUE} resolved external pointers protect library handles from finalization.}
|
|
|
22 }
|
|
|
23 \value{
|
|
|
24 \code{.dynload} returns an external pointer \code{libhandle} on success. Otherwise NULL is returned, if the library is not found or the linkage failed.
|
|
|
25
|
|
|
26 \code{.dynsym} returns an external pointer \code{address} on success. Otherwise NULL is returned, if the address was invalid or the symbol has not been found.
|
|
|
27
|
|
|
28 \code{.dynunload} always returns \code{NULL}.
|
|
|
29 }
|
|
|
30 \details{
|
|
|
31 \code{.dynload} loads a shared library into the current R process using the OS-specific dynamic linker interface.
|
|
|
32 The \code{libname} is passed \emph{as-is} directly to the dynamic linker and thus is given in OS-specific notation - see below for details.
|
|
|
33 On success, a handle to the library represented as an external pointer R objects is returned, otherwise \code{NULL}.
|
|
|
34 If \code{auto.unload} is \code{TRUE}, a finalizer function is registered that will unload the library on garbage collection via \code{.dynunload}.
|
|
|
35
|
|
|
36 \code{.dynsym} looks up symbol names in loaded libraries and resolves them to memory addresses returned as external pointer R objects.
|
|
|
37 Otherwise \code{NULL} is returned.
|
|
|
38 If \code{protect.lib} is \code{TRUE}, the library handle is \emph{protected} by resolved address external pointers from unloading.
|
|
|
39
|
|
|
40 \code{.dynunload} explicitly unreferences the loaded library specified by \code{libhandle}.
|
|
|
41
|
|
|
42 Setting both \code{auto.unload} and \code{protect.lib} to \code{TRUE}, libraries remain loaded as long as resolved symbols are in use, and they get automatic unloaded
|
|
|
43 when no resolved symbols remain.
|
|
|
44
|
|
|
45 Dynamic linkers usually hold an internal link count, such that a library can be opened multiple times via \code{.dynload}
|
|
|
46 - with a balanced number of calls to \code{.dynunload} that decreases the link count to unload the library again.
|
|
|
47
|
|
|
48 Similar functionality is available via \code{\link[base]{dyn.load}} and \code{getNativeSymbolInfo},
|
|
|
49 except that path names are filtered and no automatic unloading of libraries is supported.
|
|
|
50 }
|
|
|
51
|
|
|
52 \section{Shared library}{
|
|
|
53
|
|
|
54 Shared libraries are single files that contain compiled code, data and meta-information.
|
|
|
55 The code and data can be loaded and mapped to a process at run-time once.
|
|
|
56 Operating system platforms have slightly different schemes for naming,
|
|
|
57 searching and linking options.
|
|
|
58
|
|
|
59 \tabular{lll}{
|
|
|
60 \strong{Platform} \tab \strong{Binary format} \tab \strong{File Extension} \cr
|
|
|
61 Linux, BSD derivates and Sun Solaris \tab ELF format \tab \code{so} \cr
|
|
|
62 Darwin / Apple Mac OS X \tab Mach-O format \tab \code{dylib} \cr
|
|
|
63 Microsoft Windows \tab PE format \tab \code{dll} \cr
|
|
|
64 }
|
|
|
65
|
|
|
66 }
|
|
|
67
|
|
|
68 \section{Library search on Posix platforms (Linux,BSD,Sun Solaris)}{
|
|
|
69
|
|
|
70 The following text is taken from the Linux \code{dlopen} manual page:
|
|
|
71
|
|
|
72 These search rules will only be applied to path names that do not contain an embedded '/'.
|
|
|
73 \itemize{
|
|
|
74 \item If the \code{LD_LIBRARY_PATH} environment variable is defined to contain a colon-separated list of
|
|
|
75 directories, then these are searched.
|
|
|
76
|
|
|
77 \item The cache file \code{/etc/ld.so.cache} is checked to see whether it contains an entry for filename.
|
|
|
78
|
|
|
79 \item The directories \code{/lib} and \code{/usr/lib} are searched (in that order).
|
|
|
80 }
|
|
|
81 If the library has dependencies on other shared libraries, then these are also automatically
|
|
|
82 loaded by the dynamic linker using the same rules.
|
|
|
83 }
|
|
|
84 \section{Library search on Darwin (Mac OS X) platforms}{
|
|
|
85
|
|
|
86 The following text is taken from the Mac OS X dlopen manual page:
|
|
|
87
|
|
|
88 \code{dlopen()} searches for a compatible Mach-O file in the directories specified by a set of environment
|
|
|
89 variables and the process's current working directory. When set, the environment variables must contain
|
|
|
90 a colon-separated list of directory paths, which can be absolute or relative to the current working
|
|
|
91 directory. The environment variables are $LD_LIBRARY_PATH, $DYLD_LIBRARY_PATH, and $DYLD_FALLBACK_LIBRARY_PATH.
|
|
|
92 The first two variables have no default value. The default value of $DYLD_FALLBACK_LIBRARY_PATH
|
|
|
93 is $HOME/lib;/usr/local/lib;/usr/lib. \code{dlopen()} searches the directories specified in
|
|
|
94 the environment variables in the order they are listed.
|
|
|
95
|
|
|
96 When path doesn't contain a slash character (i.e. it is just a leaf name), \code{dlopen()} searches the following
|
|
|
97 until it finds a compatible Mach-O file: $LD_LIBRARY_PATH, $DYLD_LIBRARY_PATH,
|
|
|
98 current working directory, $DYLD_FALLBACK_LIBRARY_PATH.
|
|
|
99
|
|
|
100 When path contains a slash (i.e. a full path or a partial path) \code{dlopen()} searches the following the
|
|
|
101 following until it finds a compatible Mach-O file: $DYLD_LIBRARY_PATH (with leaf name from path ), current
|
|
|
102 working directory (for partial paths), $DYLD_FALLBACK_LIBRARY_PATH (with leaf name from path ).
|
|
|
103 }
|
|
|
104 \section{Library search on Microsoft Windows platforms}{
|
|
|
105
|
|
|
106 The following text is taken from the Window SDK Documentation:
|
|
|
107
|
|
|
108 If no file name extension is specified [...], the default library extension
|
|
|
109 \code{.dll} is appended. However, the file name string can include a trailing point character (.) to
|
|
|
110 indicate that the [shared library] module name has no extension. When no path is specified, the function searches
|
|
|
111 for loaded modules whose base name matches the base name of the module to be loaded.
|
|
|
112 If the name matches, the load succeeds. Otherwise, the function searches for the file in the
|
|
|
113 following sequence:
|
|
|
114
|
|
|
115 \itemize{
|
|
|
116
|
|
|
117 \item The directory from which the application loaded.
|
|
|
118 \item The current directory.
|
|
|
119 \item The system directory. Use the GetSystemDirectory Win32 API function to get the path of this directory.
|
|
|
120 \item The 16-bit system directory. There is no function that obtains the path of this directory, but it is searched. Windows Me/98/95: This directory does not exist.
|
|
|
121 \item The Windows directory. Use the GetWindowsDirectory Win32 API function to get the path of this directory.
|
|
|
122 \item The directories that are listed in the PATH environment variable.
|
|
|
123 }
|
|
|
124
|
|
|
125 Windows Server 2003, Windows XP SP1: The default value of \preformatted{HKLM\\System\\CurrentControlSet\\Control\\Session Manager\\SafeDllSearchMode} is 1 (current directory is searched after the system and Windows directories).
|
|
|
126
|
|
|
127 Windows XP: If \preformatted{HKLM\\System\\CurrentControlSet\\Control\\Session Manager\\SafeDllSearchMode} is 1, the current directory is searched after the system and Windows directories, but before the directories in the PATH environment variable. The default value is 0 (current directory is searched before the system and Windows directories).
|
|
|
128
|
|
|
129
|
|
|
130 The first directory searched is the one directory containing the image file used to create the calling process. Doing this allows private dynamic-link library (DLL) files associated with a process to be found without adding the process's installed directory to the PATH environment variable.
|
|
|
131
|
|
|
132 The search path can be altered using the \code{SetDllDirectory} function. This solution is recommended instead of using \code{SetCurrentDirectory} or hard-coding the full path to the DLL.
|
|
|
133
|
|
|
134 If a path is specified and there is a redirection file for the application, the function searches for the module in the application's directory. If the module exists in the application's directory, the LoadLibrary function ignores the specified path and loads the module from the application's directory. If the module does not exist in the application's directory, LoadLibrary loads the module from the specified directory. For more information, see Dynamic Link Library Redirection from the Windows SDK Documentation.
|
|
|
135 }
|
|
|
136 \section{Portability}{
|
|
|
137 The implementation is based on the \emph{dynload} library (part of the DynCall project) which has been ported
|
|
|
138 to all major R platforms (ELF (Linux,BSD,Solaris), Mach-O (Mac OS X) and Portable Executable (Win32/64)).
|
|
|
139 }
|
|
|
140 \seealso{
|
|
|
141 This facility is used by \code{\link{dynfind}} and \code{\link{dynbind}}.
|
|
|
142 Similar functionality is available from \code{\link[base]{dyn.load}} and \code{\link[base]{getNativeSymbolInfo}}.
|
|
|
143 }
|
|
|
144 \keyword{programming}
|
|
|
145 \keyword{interface}
|
