annotate R/rdyncall/man/dynfind.Rd @ 3:f5d4d5c2f750

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