Foreign {base} | R Documentation |
Functions to make calls to compiled code that has been loaded into R.
.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)
name |
a character string giving the name of a C function or
Fortran subroutine, or an object of class
|
... |
arguments to be passed to the foreign function. |
NAOK |
if |
DUP |
if |
PACKAGE |
if supplied, confine the search for the |
ENCODING |
optional name for an encoding to be assumed for character vectors. See ‘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
overrides 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.
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.
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.
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.
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.
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.
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
.)
dyn.load
.