Foreign                 package:base                 R Documentation

_F_o_r_e_i_g_n _F_u_n_c_t_i_o_n _I_n_t_e_r_f_a_c_e

_D_e_s_c_r_i_p_t_i_o_n:

     Functions to make calls to compiled code that has been loaded into
     R.

_U_s_a_g_e:

            .C(name, ..., NAOK = FALSE, DUP = TRUE, PACKAGE)
      .Fortran(name, ..., NAOK = FALSE, DUP = TRUE, PACKAGE)
     .External(name, ...)
         .Call(name, ...)

_A_r_g_u_m_e_n_t_s:

    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.

_D_e_t_a_i_l_s:

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

_V_a_l_u_e:

     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.

_A_r_g_u_m_e_n_t _t_y_p_e_s:

     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.

_H_e_a_d_e_r _f_i_l_e_s _f_o_r _e_x_t_e_r_n_a_l _c_o_d_e:

     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.

_N_o_t_e:

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

_S_e_e _A_l_s_o:

     `dyn.load'.

