

   Foreign {base}                               R Documentation

   FFoorreeiiggnn FFuunnccttiioonn IInntteerrffaaccee

   DDeessccrriippttiioonn::

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

   UUssaaggee::

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

   AArrgguummeenntts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 conven-
             tional 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Deettaaiills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.

   VVaalluue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' and `.Call' return an R object.

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

   AArrgguummeenntt ttyyppees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       complex *     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 interfac-
        ing of existing C and Fortran code.

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

        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 argu-
        ments.

   HHeeaaddeerr ffiilleess ffoorr eexxtteerrnnaall ccoodde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 `Rde-
        fines.h', as other header files are not installed and
        are even more likely to be changed.

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

   SSeeee AAllssoo::

        `dyn.load'.

