Foreign {base} | R Documentation |
Functions to make calls to compiled code that has been loaded into R.
.C(name, ..., NAOK = FALSE, DUP = TRUE, PACKAGE) .Fortran(name, ..., NAOK = FALSE, DUP = TRUE, PACKAGE) .External(name, ...) .Call(name, ...)
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. |
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.
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).
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.
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] |
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 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.
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.
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.
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.