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)
- a character string giving the name of a C function or Fortran subroutine, or an object of class
"NativeSymbol"referring to such a name.
- arguments to be passed to the foreign function. Up to 65.
Infvalues in the arguments are passed on to the foreign function. If
FALSE, the presence of
Infvalues is regarded as an error.
TRUEthen arguments are duplicated before their address is passed to C or Fortran.
- if supplied, confine the search for a character string
.NAMEto the DLL given by this argument (plus the conventional extension, ‘.so’, ‘.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, and also speeds up the search (see ‘Note’).
- For back-compatibility, accepted but ignored.
These functions are both primitive, and
.NAME is always matched to the first argument supplied (which should not be named). 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
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
|numeric||double *||double precision|
|-- or --||float *||real|
|complex||Rcomplex *||double complex|
|character||char **||[see below]|
|raw||unsigned char *||not allowed|
|list||SEXP *||not allowed|
Numeric vectors in R will be passed as type
double * to C (and as
double precision to Fortran) unless the argument has attribute
Csingle set to
single). This mechanism is only intended to be used to facilitate the interfacing of existing C and Fortran code.
Logical values are sent as
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
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
.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
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.
DUP = FALSE, character vectors cannot be used, and single precision values will not be returned.
It is safe and useful to set
DUP = FALSE if you do not change any of the variables that might be affected, e.g.,
In this case the
output variable did not exist before the call so it cannot cause trouble (but as from R 2.15.1 it is not copied even with
DUP = TRUE). If the
input variable is not changed in the C code of
Cfunction you are safe.
Fortran symbol names
All Fortran compilers known to be usable to compile R map symbol names to lower case, and so does
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.
.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.
Copying of arguments
DUP = TRUE there are up to two copies made of each argument in
Prior to R 2.15.1 there were always two 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 not 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.
This behaviour can be changed by setting
options(CBoundsCheck = TRUE). In that case raw, logical, integer, double and complex vector arguments are copied both before and after calling the compiled code. The first copy made is extended at each end by guard bytes, and on return it is checked that these are unaltered. For
.C, each element of a character vector uses guard bytes.
Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) The New S Language. Wadsworth & Brooks/Cole.
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.
PACKAGE = "" used to be accepted (but was undocumented): it is now an error.
The way pairlists were passed by
.C prior to R 2.15.0 was not as documented. This has been corrected, but the
.External interfaces are much preferred for passing anything other than atomic vectors.
Documentation reproduced from R 3.0.1. License: GPL-2.