Mercurial > pub > dyncall > bindings

comparison R/rdyncall/man/dynfind.Rd @ 0:0cfcc391201f

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
initial from svn dyncall-1745
author Daniel Adler
date Thu, 19 Mar 2015 22:26:28 +0100
parents
children
comparison
equal deleted inserted replaced
-1:000000000000 0:0cfcc391201f
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