|
0
|
1 \name{dynfind}
|
|
|
2 \alias{dynfind}
|
|
|
3 \title{Portable searching and loading of shared libraries}
|
|
|
4 \description{Function to load shared libraries using a platform-portable interface.}
|
|
|
5 \usage{
|
|
|
6 dynfind(libnames, auto.unload=TRUE)
|
|
|
7 }
|
|
|
8 \arguments{
|
|
|
9 \item{libnames}{vector of character strings specifying several short library names.}
|
|
|
10 \item{auto.unload}{logical: if \code{TRUE} then a finalizer is registered that closes the library on garbage collection. See \code{\link{.dynload}} for details.}
|
|
|
11 }
|
|
|
12 \details{
|
|
|
13 \code{dynfind} offers a platform-portable naming interface for loading a specific shared library.
|
|
|
14
|
|
|
15 The naming scheme and standard locations of shared libraries are OS-specific.
|
|
|
16 When loading a shared library dynamically at run-time across platforms via standard interfaces such as \code{\link{.dynload}} or \code{\link{dyn.load}},
|
|
|
17 a platform-test is usually needed to specify the OS-dependant library file path.
|
|
|
18
|
|
|
19 This \emph{library name problem} is encountered via breaking up the library file path into several abstract components:
|
|
|
20
|
|
|
21 \tabular{cccc}{
|
|
|
22 \emph{<location>} \tab \emph{<prefix>} \tab \emph{<libname>} \tab \emph{<suffix>} \cr
|
|
|
23 }
|
|
|
24
|
|
|
25 By permutation of values in each component and concatenation, a list of possible file paths can be derived.
|
|
|
26 \code{dynfind} goes through this list to try opening a library. On the first success, the search is stopped and the function returns.
|
|
|
27
|
|
|
28 Given that the three components \sQuote{location}, \sQuote{prefix} and \sQuote{suffix} are set up properly on a per OS basis,
|
|
|
29 the unique identification of a library is given by \sQuote{libname} - the short library name.
|
|
|
30
|
|
|
31 For some libraries, multiple \sQuote{short library name} are needed to make this mechanism work across all major platforms.
|
|
|
32 For example, to load the Standard C Library across major R platforms:
|
|
|
33
|
|
|
34 \preformatted{
|
|
|
35 lib <- dynfind(c("msvcrt","c","c.so.6"))
|
|
|
36 }
|
|
|
37
|
|
|
38 On Windows \code{MSVCRT.dll} would be loaded; \code{libc.dylib} on Mac OS X; \code{libc.so.6} on Linux and \code{libc.so} on BSD.
|
|
|
39
|
|
|
40 Here is a sample list of values for the three other components:
|
|
|
41
|
|
|
42 \itemize{
|
|
|
43 \item \sQuote{location}: \dQuote{/usr/local/lib/}, \dQuote{/Windows/System32/}.
|
|
|
44 \item \sQuote{prefix}: \dQuote{lib} (common), \dQuote{} (empty - common on Windows).
|
|
|
45 \item \sQuote{suffix}: \dQuote{.dll} (Windows), \dQuote{.so} (ELF), \dQuote{.dylib} (Mac OS X) and \dQuote{} (empty - useful for all platforms).
|
|
|
46 }
|
|
|
47
|
|
|
48 The vector of \sQuote{locations} is initialized by environment variables such as '\code{PATH}' on Windows and
|
|
|
49 \code{LD_LIBRARY_PATH} on Unix-flavour systems in additional to some hardcoded locations:
|
|
|
50 \file{/opt/local/lib},
|
|
|
51 \file{/usr/local/lib},
|
|
|
52 \file{/usr/lib} and
|
|
|
53 \file{/lib}.
|
|
|
54 (The set of hardcoded locations might expand and change within the next minor releases).
|
|
|
55
|
|
|
56 The file extension depends on the OS: '\code{.dll}' (Windows), '\code{.dylib}' (Mac OS X), '\code{.so}' (all others).
|
|
|
57
|
|
|
58 On Mac OS X, the search for a library includes the \sQuote{Frameworks} folders as well. This happens before the normal library search procedure and uses a slightly different naming pattern
|
|
|
59 in a separate search phase:
|
|
|
60
|
|
|
61 \tabular{c}{
|
|
|
62 \emph{<frameworksLocation>} \bold{Frameworks/} \emph{<libname>} \bold{.framework/} \emph{<libname>}
|
|
|
63 }
|
|
|
64
|
|
|
65 The \sQuote{frameworksLocation} is a vector of locations such as \code{/System/Library/} and \code{/Library/}.
|
|
|
66
|
|
|
67 \code{dynfind} loads a library via \code{\link{.dynload}} passing over the parameter \code{auto.unload}.
|
|
|
68
|
|
|
69 }
|
|
|
70 \value{
|
|
|
71 \code{dynfind} returns an external pointer (library handle), if search was successful.
|
|
|
72 Otherwise, if no library is located, a \code{NULL} is returned.
|
|
|
73 }
|
|
|
74 \seealso{
|
|
|
75 See \code{\link{.dynload}} for details on the loader interface to the OS-specific dynamic linker.
|
|
|
76 }
|
|
|
77 \keyword{programming}
|
|
|
78 \keyword{interface}
|
|
|
79
|
