

_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)

_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' values in the arguments
          are passed on to the foreign function.  If
          `FALSE', the presence of `NA' 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.

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

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

     These calls are typically made in conjunction with
     `dyn.load' which links DLLs to R.

_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.

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

     `dyn.load'.

