R: Foreign Function Interface

Foreign Function Interface

Usage

      .C(name, ..., NAOK=FALSE, DUP=TRUE)
.Fortran(name, ..., NAOK=FALSE, DUP=TRUE)
.External(name, ...)

Arguments

`name`	a character string giving the name of a C function or Fortran subroutine.
`...`	arguments to be passed to the foreign function.
`NAOK`	if `TRUE` then any `NA` or `NaN` or `Inf` values in the arguments are passed on to the foreign function. If `FALSE`, the presence of `NA` or `NaN` or `Inf` values is regarded as an error.
`DUP`	if `TRUE` then arguments are ``duplicated'' before their address is passed to C or Fortran.

Description

The functions .C and .Fortran can be used to make calls to C and Fortran code.

.External can be used to call compiled code that uses R objects in the same way as internal R functions. There is no documentation to help you write this sort of code.

Value

The functions .C and .Fortran return a list similar to the ... list of arguments passed in, but reflecting any changes made by the C or Fortran code.

.External returns an R object.

These calls are typically made in conjunction with dyn.load which links DLLs to R.

Argument types

The mapping of the types of R arguments to C or Fortran arguments in .C or .Fortran is

R	C	Fortran
integer	int *	integer
real	double *	double precision
complex	complex *	double precision
logical	int *	integer
character	char **	[compiler dependent]
list	void * (SEXP *)
other	void * (SEXP)

The C type complex is defined in `Complex.h' as a typedef struct {double r; double i;}.

Note: The C types corresponding to integer and logical are int, not long as in S.

Character strings are passed as C arrays of character strings to Fortran: the first string may be usable if its length is passed separately.

Lists, functions, expressions, environments and other language elements are passed as generic pointers (void *). R functions can be invoked using call_S or call_R and can be passed lists or the simple types as arguments.

Header files for external code

Writing code for use with .External will typically require access to the header files in the src/include. These are not copied by make install and so may not be available in an installed version of R.

Note

DUP=FALSE is dangerous.

There are two important dangers with DUP=FALSE. The first is that garbage collection may move the object, resulting in the pointers pointing nowhere useful and causing hard-to-reproduce bugs.

The second is that if you pass a formal parameter of the calling function to .C/.Fortran with DUP=FALSE, it may not necessarily be copied. You may be able to change not only the local variable but the variable one level up. This will also be very hard to trace.

1. If your C/Fortran routine calls back any R function including S_alloc/R_alloc then do not use DUP=FALSE. Do not even think about it. Calling almost any R function could trigger garbage collection.

2. If you don't trigger garbage collection it is safe and useful to set DUP=FALSE if you don't change any of the variables that might be affected, e.g.,

.C("Cfunction", input=x, output=numeric(10)).

In this case the output variable didn't exist before the call so it can't cause trouble. If the input variable is not changed in Cfunction you are safe.