|
0
|
1 \name{dynbind}
|
|
|
2 \alias{dynbind}
|
|
|
3 \title{Binding C library functions via thin call wrappers}
|
|
|
4 \description{Function to bind several foreign functions of a C library via installation of thin R call wrappers.}
|
|
|
5 \usage{
|
|
|
6 dynbind(libnames, signature,
|
|
|
7 envir=parent.frame(), callmode="default",
|
|
|
8 pat=NULL, replace=NULL, funcptr=FALSE)
|
|
|
9 }
|
|
|
10 \arguments{
|
|
|
11 \item{libnames}{vector of character strings giving short library names of the shared library to be loaded. See \code{\link{dynfind}} for details.}
|
|
|
12 \item{signature}{character string specifying the \emph{library signature} that determines the set of foreign function names and types. See details.}
|
|
|
13 \item{envir}{the environment to use for installation of call wrappers.}
|
|
|
14 \item{callmode}{character string specifying the calling convention, see details.}
|
|
|
15 \item{pat}{NULL or regular expression character string applied to symbolic names.}
|
|
|
16 \item{replace}{NULL or replacement character string applied to \code{pat} part of symbolic names.}
|
|
|
17 \item{funcptr}{logical, that indicates whether foreign objects refer to functions (\code{FALSE}, default) or to function poiner variables (\code{TRUE} rarely needed).}
|
|
|
18 }
|
|
|
19 \details{
|
|
|
20 \code{dynbind} makes a set of C functions available to R through installation of thin call wrappers.
|
|
|
21 The set of functions, including the symbolic name and function type, is specified by \code{signature} ; a character string that encodes a
|
|
|
22 library signature:
|
|
|
23
|
|
|
24 The \strong{library signature} is a compact plain-text format to specify a set of function bindings.
|
|
|
25 It consists of function names and corresponding \link[=call signature]{call signatures}. Function bindings are separated
|
|
|
26 by \sQuote{;} (semicolon) ; white spaces (including tab and new line) are allowed before and after semicolon.
|
|
|
27
|
|
|
28 \tabular{c}{
|
|
|
29 \emph{function-name} \code{(} \emph{call-signature} \code{;} \ldots \cr
|
|
|
30 }
|
|
|
31
|
|
|
32 Here is an example that specifies three function bindings to the OpenGL library:
|
|
|
33 \preformatted{"glAccum(If)v ; glClear(I)v ; glClearColor(ffff)v ;"}
|
|
|
34
|
|
|
35 Symbolic names are resolved using the library specified by \code{libnames} using \code{\link{dynfind}} for loading.
|
|
|
36 For each function, a thin call wrapper function is created using the following template:
|
|
|
37
|
|
|
38 \preformatted{ function(...) .dyncall.<MODE> ( <TARGET>, <SIGNATURE>, ... ) }
|
|
|
39
|
|
|
40 \code{<MODE>} is replaced by \code{callmode} argument, see \code{\link{.dyncall}} for details on calling conventions.
|
|
|
41 \code{<TARGET>} is replaced by the external pointer, resolved by the \sQuote{function-name}.
|
|
|
42 \code{<SIGNATURE>} is replaced by the call signature string contained in \code{signature}.
|
|
|
43
|
|
|
44 The call wrapper is installed in the environment given by \code{envir}.
|
|
|
45 The assignment name is obtained from the function signature.
|
|
|
46 If \code{pat} and \code{replace} is given, a text replacement is applied to the name before assignment, useful for basic C name space mangling such as exchanging the prefix.
|
|
|
47
|
|
|
48 As a special case, \code{dynbind} supports binding of pointer-to-function variables, indicated by setting \code{funcptr} to \code{TRUE}, in which case \code{<TARGET>}
|
|
|
49 is replaced with the expression \code{.unpack(<TARGET>,"p",0)} in order to dereference \code{<TARGET>} as a pointer-to-function variable at call-time.
|
|
|
50 }
|
|
|
51
|
|
|
52 \value{
|
|
|
53 The function returns a list with two fields:
|
|
|
54 \item{libhandle}{External pointer returned by \code{\link{.dynload}}.}
|
|
|
55 \item{unresolved.symbols}{vector of character strings, the names of unresolved symbols.}
|
|
|
56
|
|
|
57 As a side effect, for each wrapper, \code{dynbind} assigns the \sQuote{function-name} to the corresponding call wrapper function in the environment given by \code{envir}.
|
|
|
58
|
|
|
59 If no shared library is found, an error is reported.
|
|
|
60 }
|
|
|
61 \examples{
|
|
|
62 \donttest{
|
|
|
63 # Install two wrappers to functions of the R shared C library.
|
|
|
64 info <- dynbind("R","
|
|
|
65 R_ShowMessage(Z)v;
|
|
|
66 R_rsort(pi)v;
|
|
|
67 ")
|
|
|
68 R_ShowMessage("hello")
|
|
|
69 }
|
|
|
70 }
|
|
|
71 \seealso{
|
|
|
72 \code{\link{.dyncall}} for details on call signatures and calling conventions,
|
|
|
73 \code{\link{dynfind}} for details on short library names,
|
|
|
74 \code{\link{.unpack}} for details on reading low-level memory (e.g. dereferencing of (function) pointer variables).
|
|
|
75 }
|
|
|
76 \keyword{programming}
|
|
|
77 \keyword{interface}
|
|
|
78
|
