annotate R/rdyncall/man/dynbind.Rd @ 0:0cfcc391201f

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