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}
+