annotate R/rdyncall/man/dynload.Rd @ 0:0cfcc391201f

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