Mercurial > pub > dyncall > bindings
diff R/rdc/man/rdc.Rd @ 0:0cfcc391201f
initial from svn dyncall-1745
author | Daniel Adler |
---|---|
date | Thu, 19 Mar 2015 22:26:28 +0100 |
parents | |
children |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/R/rdc/man/rdc.Rd Thu Mar 19 22:26:28 2015 +0100 @@ -0,0 +1,111 @@ +\name{rdc} +\alias{rdcLoad} +\alias{rdcFree} +\alias{rdcFind} +\alias{rdcCall} +\alias{rdcPath} +\alias{rdcUnpath} +\alias{rdcShowPath} +\alias{rdcUnpack1} +\alias{rdcDataPtr} +\title{invoke dynamic calls to foreign code} +\description{ +Invoke foreign function calls with support for loading modules and resolving symbols. +} +\usage{ +libhandle <- rdcLoad(libpath) +rdcFree(libhandle) +funcptr <- rdcFind(libhandle, symbol) +result <- rdcCall(funcptr, signature, ...) +rdcPath(addpath) +rdcUnpath(delpath) +rdcShowPath() +rdcUnpack1(object, offset, sigchar) +rdcDataPtr(object, offset = 0) +} + +\arguments{ + \item{libpath}{a file path to dynamic linked library(DLL).} + \item{libhandle}{an external pointer representing an operating-system specific handle to an opened DLL.} + \item{symbol}{a character string, specifying a function name symbol in a DLL.} + \item{funcptr}{an external pointer representing a pointer to function resolved by a symbol} + \item{signature}{a character string specifying the argument and return type of a function call, see Details below for more information.} + \item{addpath,delpath}{a directory path from where dynamic linked libraries should be loaded.} + \item{object}{An atomic object (scalar, vector, matrix or array).} + \item{offset}{An integer specifying an offset from the start of the linear data memory in bytes.} +} + +\details{ +The rdc package provides tools to establish flexible function calls to low-level precompiled code. +It is more flexible than \code{\link{.C}} and has the same type-unsafety dangers. +One can make arbitrary C (and C++ member-) function calls. +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 +the supported typeset and calling convention). +It makes use of signature strings to specify +the function prototyp to call. +to providing a thin binding layer between the core +dyncall library and the R programming language. + +The loading and unloading of code modules (*.DLL files on windows, *.dylib files on darwin and *.so files on other *nix flavour OSs) +is done using rdcLoad, similar to \code{\link{dyn.load}}. While \code{\link{dyn.load}} loads a DLL to the R run-time process, +rdcLoad returns the module handle as an external pointer. + +Symbol lookup is done using \code{rdcFind} and returns an external pointer pointing to the foreign function. + +The \code{rdcCall} function does invoke the function call. +It requires the \code{signature} character string argument, which consists of a series of type codes (given as ordinary characters) to +specify the argument types and the expected return type of the foreign function call which are separated by an ')' character. + +\deqn{sigchar_{arg_0} sigchar_{arg_1} \ldots ')' sigchar_{return}}{<sigchar-arg0> <sigchar-arg1> \ldots ')' <sigchar-return>} + +A signature character encodes the C type at the given argument position or return-type. + +\tabular{cll}{ +Signature char \tab C type \tab accepted R data types\cr +\sQuote{B} \tab \code{bool} \tab coerced to logical vector, first item\cr +\sQuote{c} \tab \code{char} \tab not yet implemented\cr +\sQuote{s} \tab \code{short} \tab not yet implemented\cr +\sQuote{i} \tab \code{int} \tab coerced to integer vector, first item\cr +\sQuote{l} \tab \code{long} \tab not yet implemented\cr +\sQuote{f} \tab \code{float} \tab coerced to numeric, first item casted to float\cr +\sQuote{d} \tab \code{double} \tab coerced to numeric, first item\cr +\sQuote{L} \tab \code{long long} \tab coerced to numeric, first item casted to long long\cr +\sQuote{p} \tab \code{void*} \tab external pointer or coerced to string vector, first item\cr +\sQuote{S} \tab \code{char*} \tab coerced to string vector, first item\cr +\sQuote{v} \tab \code{void} \tab no return type\cr +} + +The order of the arguments is left-to-right according to the C prototyp function declaration. E.g. + +e.g. the signature string of the function \samp{double foobar(int a, long long b, float c);} is \code{"iLf)d"}. + +} +\examples{ + +# load platform-specific standard C DLL + +clibname <- "libc" +if (.Platform$OS.type == "windows") clibname <- "msvcrt" +if (.Platform$OS.type == "darwin") clibname <- "libc.dylib" + +clib <- rdcLoad(clibname) + +# call sqrt function + +sqrt.fp <- rdcFind(clib,"sqrt") +print( rdcCall(sqrt.fp, "d)d", 144) ) + +} +\references{ + Adler, D., Philipp, T. (2008) \emph{Dyncall Library}. + \url{http://dyncall.org} +} +\author { + Daniel Adler \email{dadler@uni-goettingen} +} +\examples { + # bla + +} +\keyword{programming::interface} +