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
