|
0
|
1 \name{rdc}
|
|
|
2 \alias{rdcLoad}
|
|
|
3 \alias{rdcFree}
|
|
|
4 \alias{rdcFind}
|
|
|
5 \alias{rdcCall}
|
|
|
6 \alias{rdcPath}
|
|
|
7 \alias{rdcUnpath}
|
|
|
8 \alias{rdcShowPath}
|
|
|
9 \alias{rdcUnpack1}
|
|
|
10 \alias{rdcDataPtr}
|
|
|
11 \title{invoke dynamic calls to foreign code}
|
|
|
12 \description{
|
|
|
13 Invoke foreign function calls with support for loading modules and resolving symbols.
|
|
|
14 }
|
|
|
15 \usage{
|
|
|
16 libhandle <- rdcLoad(libpath)
|
|
|
17 rdcFree(libhandle)
|
|
|
18 funcptr <- rdcFind(libhandle, symbol)
|
|
|
19 result <- rdcCall(funcptr, signature, ...)
|
|
|
20 rdcPath(addpath)
|
|
|
21 rdcUnpath(delpath)
|
|
|
22 rdcShowPath()
|
|
|
23 rdcUnpack1(object, offset, sigchar)
|
|
|
24 rdcDataPtr(object, offset = 0)
|
|
|
25 }
|
|
|
26
|
|
|
27 \arguments{
|
|
|
28 \item{libpath}{a file path to dynamic linked library(DLL).}
|
|
|
29 \item{libhandle}{an external pointer representing an operating-system specific handle to an opened DLL.}
|
|
|
30 \item{symbol}{a character string, specifying a function name symbol in a DLL.}
|
|
|
31 \item{funcptr}{an external pointer representing a pointer to function resolved by a symbol}
|
|
|
32 \item{signature}{a character string specifying the argument and return type of a function call, see Details below for more information.}
|
|
|
33 \item{addpath,delpath}{a directory path from where dynamic linked libraries should be loaded.}
|
|
|
34 \item{object}{An atomic object (scalar, vector, matrix or array).}
|
|
|
35 \item{offset}{An integer specifying an offset from the start of the linear data memory in bytes.}
|
|
|
36 }
|
|
|
37
|
|
|
38 \details{
|
|
|
39 The rdc package provides tools to establish flexible function calls to low-level precompiled code.
|
|
|
40 It is more flexible than \code{\link{.C}} and has the same type-unsafety dangers.
|
|
|
41 One can make arbitrary C (and C++ member-) function calls.
|
|
|
42 The language binding was designed to help write glue code to low-level C libraries in R (if the target library function is compatible with
|
|
|
43 the supported typeset and calling convention).
|
|
|
44 It makes use of signature strings to specify
|
|
|
45 the function prototyp to call.
|
|
|
46 to providing a thin binding layer between the core
|
|
|
47 dyncall library and the R programming language.
|
|
|
48
|
|
|
49 The loading and unloading of code modules (*.DLL files on windows, *.dylib files on darwin and *.so files on other *nix flavour OSs)
|
|
|
50 is done using rdcLoad, similar to \code{\link{dyn.load}}. While \code{\link{dyn.load}} loads a DLL to the R run-time process,
|
|
|
51 rdcLoad returns the module handle as an external pointer.
|
|
|
52
|
|
|
53 Symbol lookup is done using \code{rdcFind} and returns an external pointer pointing to the foreign function.
|
|
|
54
|
|
|
55 The \code{rdcCall} function does invoke the function call.
|
|
|
56 It requires the \code{signature} character string argument, which consists of a series of type codes (given as ordinary characters) to
|
|
|
57 specify the argument types and the expected return type of the foreign function call which are separated by an ')' character.
|
|
|
58
|
|
|
59 \deqn{sigchar_{arg_0} sigchar_{arg_1} \ldots ')' sigchar_{return}}{<sigchar-arg0> <sigchar-arg1> \ldots ')' <sigchar-return>}
|
|
|
60
|
|
|
61 A signature character encodes the C type at the given argument position or return-type.
|
|
|
62
|
|
|
63 \tabular{cll}{
|
|
|
64 Signature char \tab C type \tab accepted R data types\cr
|
|
|
65 \sQuote{B} \tab \code{bool} \tab coerced to logical vector, first item\cr
|
|
|
66 \sQuote{c} \tab \code{char} \tab not yet implemented\cr
|
|
|
67 \sQuote{s} \tab \code{short} \tab not yet implemented\cr
|
|
|
68 \sQuote{i} \tab \code{int} \tab coerced to integer vector, first item\cr
|
|
|
69 \sQuote{l} \tab \code{long} \tab not yet implemented\cr
|
|
|
70 \sQuote{f} \tab \code{float} \tab coerced to numeric, first item casted to float\cr
|
|
|
71 \sQuote{d} \tab \code{double} \tab coerced to numeric, first item\cr
|
|
|
72 \sQuote{L} \tab \code{long long} \tab coerced to numeric, first item casted to long long\cr
|
|
|
73 \sQuote{p} \tab \code{void*} \tab external pointer or coerced to string vector, first item\cr
|
|
|
74 \sQuote{S} \tab \code{char*} \tab coerced to string vector, first item\cr
|
|
|
75 \sQuote{v} \tab \code{void} \tab no return type\cr
|
|
|
76 }
|
|
|
77
|
|
|
78 The order of the arguments is left-to-right according to the C prototyp function declaration. E.g.
|
|
|
79
|
|
|
80 e.g. the signature string of the function \samp{double foobar(int a, long long b, float c);} is \code{"iLf)d"}.
|
|
|
81
|
|
|
82 }
|
|
|
83 \examples{
|
|
|
84
|
|
|
85 # load platform-specific standard C DLL
|
|
|
86
|
|
|
87 clibname <- "libc"
|
|
|
88 if (.Platform$OS.type == "windows") clibname <- "msvcrt"
|
|
|
89 if (.Platform$OS.type == "darwin") clibname <- "libc.dylib"
|
|
|
90
|
|
|
91 clib <- rdcLoad(clibname)
|
|
|
92
|
|
|
93 # call sqrt function
|
|
|
94
|
|
|
95 sqrt.fp <- rdcFind(clib,"sqrt")
|
|
|
96 print( rdcCall(sqrt.fp, "d)d", 144) )
|
|
|
97
|
|
|
98 }
|
|
|
99 \references{
|
|
|
100 Adler, D., Philipp, T. (2008) \emph{Dyncall Library}.
|
|
|
101 \url{http://dyncall.org}
|
|
|
102 }
|
|
|
103 \author {
|
|
|
104 Daniel Adler \email{dadler@uni-goettingen}
|
|
|
105 }
|
|
|
106 \examples {
|
|
|
107 # bla
|
|
|
108
|
|
|
109 }
|
|
|
110 \keyword{programming::interface}
|
|
|
111
|
