Foreign {base}R Documentation

Foreign Function Interface

Description

Functions to make calls to compiled code that has been loaded into R.

Usage

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

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 by using this argument that no other package can override their external symbols. Use PACKAGE="base" for symbols linked in to R.

Details

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

.External and .External.graphics can be used to call compiled code that uses R objects in the same way as internal R functions.

.Call and .Call.graphics 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.

For details about how to write code to use with .Call and .External, see the chapter on “System and foreign language interfaces” in “Writing R Extensions” in the ‘doc/manual’ subdirectory of the R source tree.

Fortran names will need to be in the case as mapped by the compiler, for all known R platforms in lower case. They should not include any trailing underscore if one is appended by the compiler.

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, .Call, .External.graphics, and .Call.graphics return an R object.
These calls are typically made in conjunction with dyn.load which links DLLs to R.
The .graphics versions of .Call and .External are used when calling code which makes low-level graphics calls. They take additional steps to ensure that the device driver display lists are updated correctly.

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 Rcomplex * double complex
logical int * integer
character char ** [see below]
raw unsigned char * not allowed
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 used to facilitate the interfacing of existing C and Fortran code.

The C type Rcomplex 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 availability 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. This difference matters on 64-bit platforms.

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. (How well this works, or even if it works at all, depends on the C and Fortran compilers and the platform.)

Missing (NA) string values are passed to .C as the string "NA". As the C char type can represent all possible bit patterns there appears to be no way to distinguish missing strings from the string "NA". If this distinction is important use .Call.

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 *. Note that you cannot assign values to the elements of the list within the C routine. Assigning values to elements of the array corresponding to the list bypasses R's memory management/garbage collection and will cause problems. Essentially, the array corresponding to the list is read-only. If you need to return S objects created within the C routine, use the .Call interface.

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 two dangers with using DUP=FALSE.

The first is that if you pass a local variable to .C/.Fortran with DUP=FALSE, your compiled code can alter the local variable and not just the copy in the return list. Worse, if you pass a local variable that is a formal parameter of the calling function, you may be able to change not only the local variable but the variable one level up. This will be very hard to trace.

The second 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. New code using R objects should be written using .Call or .External, so this is now only a minor issue.

(Prior to R version 1.2.0 there has a third danger, that objects could be moved in memory by the garbage collector. The current garbage collector never moves objects.)

It is safe and useful to set DUP=FALSE if you do not change any of the variables that might be affected, e.g.,

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

In this case the output variable did not exist before the call so it cannot cause trouble. If the input variable is not changed in the C code of Cfunction you are safe.

Neither .Call nor .External copy their arguments. You should treat arguments you receive through these interfaces as read-only.

References

Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole. (.C and .Fortran.)

Chambers, J. M. (1998) Programming with Data. A Guide to the S Language. Springer. (.Call.)

See Also

dyn.load.


[Package base version 2.2.1 Index]