\Header{Foreign}{Foreign Function Interface}
\alias{.C}{Foreign}
\alias{.Fortran}{Foreign}
\alias{.External}{Foreign}
\keyword{programming}{Foreign}
\begin{Usage}
\begin{verbatim}
      .C(name, ..., NAOK=FALSE, DUP=TRUE)
.Fortran(name, ..., NAOK=FALSE, DUP=TRUE)
.External(name, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\texttt{name}] a character string giving the name of a C function or
Fortran subroutine.
\item[\texttt{...}] arguments to be passed to the foreign function.
\item[\texttt{NAOK}] if \texttt{TRUE} then any \texttt{NA} or \texttt{NaN} or
\texttt{Inf} values in the arguments are passed on to the foreign function.
If \texttt{FALSE}, the presence of \texttt{NA}  or \texttt{NaN} or
\texttt{Inf} values is regarded as an error.
\item[\texttt{DUP}] if \texttt{TRUE} then arguments are ``duplicated'' before their
address is passed to C or Fortran.
\end{ldescription}
\end{Arguments}
\begin{Description}
The functions \texttt{.C} and \texttt{.Fortran} can be used to
make calls to C and Fortran code.

\texttt{.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.\end{Description}
\begin{Value}
The functions \texttt{.C} and \texttt{.Fortran} return a list similar to the \texttt{...}
list of arguments passed in, but reflecting any
changes made by the C or Fortran code.

\texttt{.External} returns an \R\ object.

These calls are typically made in conjunction with
\texttt{\Link{dyn.load}} which links DLLs to \R.\end{Value}
\begin{Section}{Argument types}
The mapping of the types of \R\ arguments to C or Fortran arguments
in \texttt{.C} or \texttt{.Fortran} is
\Tabular{lll}{
\    R &     C &     Fortran\\{}
integer & int * & integer\\{}
real & double * & double precision\\{}
complex & complex * & double precision\\{}
logical & int * & integer \\{}
character & char ** & [compiler dependent]\\{}
list & void * (SEXP *)& \\{}
other & void * (SEXP)& \\{}
}
The C type \texttt{complex} is defined in \file{Complex.h} as a
\texttt{typedef struct \{double r; double i;\}}.

\emph{Note:} The C types corresponding to \texttt{integer} and
\texttt{logical} are \texttt{int}, not \texttt{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 (\texttt{void *}). R functions can
be invoked using \texttt{call\_S} or \texttt{call\_R} and can be passed
lists or the simple types as arguments.\end{Section}
\begin{Section}{Header files for external code}
Writing code for use with \texttt{.External} will typically use
internal \R\ structures. If possible use just those in
\file{Rinternals.h}, as other header files are not installed and are
even more likely to be changed.\end{Section}
\begin{Note}
\emph{\texttt{DUP=FALSE} is dangerous.}

There are two important dangers with \texttt{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 \texttt{.C}/\texttt{.Fortran} with \texttt{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
\texttt{S\_alloc}/\texttt{R\_alloc} then do not use \texttt{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
\texttt{DUP=FALSE} if you don't change any of the variables that might be
affected, e.g.,

\texttt{.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 \texttt{Cfunction} you are
safe.\end{Note}
\begin{SeeAlso}
\texttt{\Link{dyn.load}}.\end{SeeAlso}

