R: Foreign Function Interface

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, ENCODING)
     .Fortran(name, ..., NAOK = FALSE, DUP = TRUE, PACKAGE, ENCODING)
    .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, or an object of class `"NativeSymbolInfo"` or `"NativeSymbol"` referring to such a name.
`...` | 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.
`ENCODING` | optional name for an encoding to be assumed for character vectors. See ‘Details’.

### Details

The functions `.C` and `.Fortran` can be used to make calls to compiled 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 to 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.

Specifying `ENCODING` overrrides any declared encodings (see `link{Encoding}`) which are otherwise used to translate to the current locale before passing the strings to the compiled code.

For details about how to write code to use with `.Call` and `.External`, see the chapter on “System and foreign language interfaces” in the “Writing R Extensions” manual.

### 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 true 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.

### Warning

`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.

In addition, character vectors and lists cannot be used with `DUP=FALSE`.

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.

### Fortran symbol names

All compilers that can be used with R map symbol names to lower case, and so does `.Fortran`.

Symbol names containing underscores are not valid Fortran 77 (although they are valid in Fortran 9x). Many Fortran 77 compilers (including `g77`) will allow them but translate them in a different way to names not containing underscores. Such names will work with `.Fortran`, but portable code should not use Fortran names containing underscores.

Use `.Fortran` with care for compiled Fortran 9x code: it may not work if the Fortran 9x compiler used differs from the Fortran compiler used when configuring R, especially if the subroutine name is not lower-case or includes an underscore.

### Header files for external code

Writing code for use with `.External` and `.Call` will need to 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.

### 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.6.2 Index]