| 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)
.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. Up to 65. |
NAOK |
if |
DUP |
if |
PACKAGE |
if supplied, confine the search for the This is intended to add safety for packages, which can ensure by using this argument that no other package can override their external symbols, and also speeds up the search (see ‘Note’). |
ENCODING |
optional name for an encoding to be assumed for
character vectors. Allowed but ignored for |
These functions can be used to make calls to compiled C and Fortran 77
code. Later interfaces are .Call and
.External.
Character strings will be translated from the value of ENCODING
or any declared encoding (see Encoding) to the current
locale before being passed to the compiled C code. They will be
returned encoded in the current locale unless ENCODING was
specified, when the output strings are translated to the specified
encoding. This is deprecated: convert code to use iconv.
These functions are all primitive, and .NAME is always
matched to the first argument supplied (which if named must partially
match .NAME). The other named arguments follow ...
and so cannot be abbreviated. For clarity, should avoid using names
in the arguments passed to ... that match or partially match
.NAME.
A list similar to the ... list of arguments passed in
(including any names given to the arguments), but reflecting any
changes made by the C or Fortran code.
The mapping of the types of R arguments to C or Fortran arguments 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) DUP is true
and (ii) 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;}. It may or may not be
equivalent to the C99 double complex type, depending on the
compiler used.
Logical values are sent as 0 (FALSE), 1
(TRUE) or INT_MIN = -2147483648 (NA, but only if
NAOK = TRUE), and the compiled code should return one of these
three values: however non-zero values other than INT_MIN are
mapped to TRUE.
Note: The C types corresponding to integer and
logical are int, not long as in S. This
difference matters on most 64-bit platforms, where int is
32-bit and long is 64-bit (but not on 64-bit Windows).
Note: The Fortran type corresponding to logical is
integer, not logical: the difference matters on some
Fortran compilers.
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.
.Fortran passes the first (only )character string of a character
vector is passed as a C character array to Fortran: that 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, and even if it works at all, depends on the C and Fortran
compilers and the platform.)
Lists, functions are other R objects can (for historical reasons) be
passed to .C, but the .Call interface is much
preferred. All inputs apart from atomic vectors should be regarded as
read-only, and all apart from vectors (including lists), functions and
environments are now deprecated.
DUP = FALSE is dangerous.
People concerned about memory usage are strongly recommended to use
the .Call interface instead of these interfaces.
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.
Character vectors 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.
Note that if DUP = TRUE there are up to two copies involved.
Prior to R 2.15.1 this was always the case for vectors (one before
calling the compiled code and one to collect the results), and this is
still the case for character vectors. For other atomic vectors, the
argument is copied before calling the compiled code if it is not
otherwise used in the calling code (such as output in the
example above). Non-atomic-vector objects are read-only to the C code
and are never copied.
All Fortran compilers known to be usable to compile 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 will allow
them but may translate them in a different way to names not containing
underscores. Such names will often work with .Fortran (since
how they are translated is detected when R is built and the
information used by .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 77 compiler
used when configuring R, especially if the subroutine name is not
lower-case or includes an underscore. It is also possible to use
.C and do any necessary symbol-name translation yourself.
If one of these functions is to be used frequently, do specify
PACKAGE (to confine the search to a single DLL) or pass
.NAME as one of the native symbol objects. Searching for
symbols can take a long time, especially when many namespaces are loaded.
You may see PACKAGE = "base" for symbols linked into R. Do
not use this in your own code: such symbols are not part of the API
and may be changed without warning.
The way pairlists were passed by .C prior to R 2.15.0
was not as documented. This has been corrected, but the
.Call and .External interfaces are much
preferred for passing anything other than atomic vectors.
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
The ‘Writing R Extensions’ manual.