

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

           .C(name, ..., NAOK=FALSE, DUP=TRUE)
     .Fortran(name, ..., NAOK=FALSE, DUP=TRUE)
     .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.

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

     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.
     There is no documentation to help you write this sort
     of code.

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

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

     The functions `.C' and `.Fortran' return a list similar
     to the `...'  list of arguments passed in, but reflect-
     ing any changes made by the C or Fortran code.

     `.External' returns 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
      real          double *           double precision
      complex       complex *          double complex
      logical       int *              integer
      character     char **            [compiler dependent]
      list          void * (SEXP *)
      other         void * (SEXP)

     The C type `complex' is defined in `Complex.h' as a
     `typedef struct {double r; double i;}'. Fortran type
     `double complex' is an extension to the Fortran stan-
     dard, and the availibility of a mapping of `complex' to
     Fortran may be compiler dependent.

     Note: The C types corresponding to `integer' and `logi-
     cal' are `int', not `long' as in S.

     Character strings are passed as C arrays of character
     strings to Fortran: the first string may be usable if
     its length is passed separately.

     Lists, functions, expressions, environments and other
     language elements are passed as generic pointers (`void
     *'). 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' will typically
     use internal R structures. If possible use just those
     in `Rinternals.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 two 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.

     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 vari-
     able is not changed in `Cfunction' you are safe.

     Also note that with `DUP=FALSE', lists are passed in
     the internal R format `(SEXP)' like any other non-
     atomic object. The accessor macros in `Rinternals.h'
     are needed to get at the list elements.

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

     `dyn.load'.

