Mercurial > pub > dyncall > bindings

comparison R/rdyncall/man/dynbind.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{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