R: Foreign Function Interface

Foreign {base}

R Documentation

Foreign Function Interface

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.

.Call can be used call compiled code which makes use of internal R objects. The arguments are passed to the C code as a sequence of R objects. It is included to provide compatibility with S version 4.

Usage

       .C(name, ..., NAOK=FALSE, DUP=TRUE, PACKAGE)
 .Fortran(name, ..., NAOK=FALSE, DUP=TRUE, PACKAGE)
.External(name, ...)
    .Call(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.

PACKAGE

if supplied, confine the search for the name to the DLL given by this argument (plus the conventional extension, .so, .sl, .dll, ...). This is intended to add safety for packages, which can ensure that no other package can override their external symbols by using this argument. Use PACKAGE="base" for symbols linked in to R.

Details

For details about how to write code to use with .Call and .External see the ‘R-external’ manual which can be made from files in the R source tree.

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 and .Call return 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
numeric	double *	double precision
-- or --	float *	real
complex	complex *	double complex
logical	int *	integer
character	char **	[see below]
list	SEXP *	not allowed
other	SEXP	not allowed

Numeric vectors in R will be passed as type double * to C (and as double precision to Fortran) unless (i) .C or .Fortran is used, (ii) DUP is false and (iii) the argument has attribute Csingle set to TRUE (use as.single or single). This mechanism is only intended to be use to facilitate the interfacing of existing C and Fortran code.

The C type complex is defined in ‘Complex.h’ as a typedef struct {double r; double i;}. Fortran type double complex is an extension to the Fortran standard, and the availibility of a mapping of complex to Fortran may be compiler dependent.

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

The first character string of a character vector is passed as a C character array to Fortran: that string may be usable as character*255 if its true length is passed separately. Only up to 255 characters of the string are passed back.

Functions, expressions, environments and other language elements are passed as the internal R pointer type SEXP. This type is defined in Rinternals.h or the arguments can be declared as generic pointers, void *. Lists are passed as C arrays of SEXP and can be declared as void * or SEXP *.

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 and .Call will use internal R structures. If possible use just those defined in ‘Rinternals.h’ and/or the macros in ‘Rdefines.h’, as other header files are not installed and are even more likely to be changed.

Note

DUP=FALSE is dangerous.

There are three 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.

The third is that lists are passed as a single R SEXP with DUP=FALSE, not as an array of SEXP. This means the accessor macros in Rinternals.h are needed to get at the list elements and the lists cannot be passed to call_S/call_R.

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.