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, ..., PACKAGE)
                  .Call(name, ..., PACKAGE)
     .External.graphics(name, ..., PACKAGE)
         .Call.graphics(name, ..., PACKAGE)

_A_r_g_u_m_e_n_t_s:

    name: a character string giving the name of a C function or Fortran
          subroutine, or an object of class '"NativeSymbolInfo"' or
          '"NativeSymbol"' referring to such a name.

     ...: 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 by using this argument that no
          other package can override their external symbols.  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' and '.External.graphics' can be used to call compiled
     code that uses R objects in the same way as internal R functions.

     '.Call' and '.Call.graphics' 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.

     Fortran names will need to be in the case as mapped by the
     compiler, for all known R platforms in lower case.  They should
     not include any trailing underscore if one is appended by the
     compiler.

_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', '.Call', '.External.graphics', and '.Call.graphics'
     return an R object.

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

     The '.graphics' versions of '.Call' and '.External' are used when
     calling code which makes low-level graphics calls. They take
     additional steps to ensure that the device driver display lists
     are updated correctly.

_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]
       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) '.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 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;}'.  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.  This difference matters on 64-bit
     platforms.

     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.  (How well this
     works, or even if it works at all, depends on the C and Fortran
     compilers and the platform.)

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

     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 *'. Note that you cannot
     assign values to the elements of the list within the C routine.
     Assigning values to elements of the array corresponding to the
     list bypasses R's memory management/garbage collection and will
     cause problems.  Essentially, the array corresponding to the list
     is read-only. If you need to return S objects created within the C
     routine,  use the '.Call' interface.

     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 two dangers with using 'DUP=FALSE'.

     The first is that 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.

     The second 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'.  New code
     using R objects should be written using '.Call' or '.External', so
     this is now only a minor issue.

     (Prior to R version 1.2.0 there has a third danger, that objects
     could be moved in memory by the garbage collector. The current
     garbage collector never moves objects.)

     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.

     Neither '.Call' nor '.External' copy their arguments.  You should
     treat arguments you receive through these interfaces as read-only.

     Symbol names containing underscores are not valid Fortran 77
     (although they are valid in Fortran 9x).  Many Fortran 77
     compilers (including 'g77') will allow them but translate them in
     a different way to '.Fortran'.  Portable code should not use
     Fortran names containing underscores for entry points to be called
     from R.

_R_e_f_e_r_e_n_c_e_s:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole. ('.C' and '.Fortran'.)

     Chambers, J. M. (1998) _Programming with Data. A Guide to the S
     Language_. Springer. ('.Call'.)

_S_e_e _A_l_s_o:

     'dyn.load'.

