EVOLUTION-MANAGER
Edit File: CallExternal.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Modern Interfaces to C/C++ code</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for CallExternal {base}"><tr><td>CallExternal {base}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Modern Interfaces to C/C++ code</h2> <h3>Description</h3> <p>Functions to pass <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> objects to compiled C/C++ code that has been loaded into <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span>. </p> <h3>Usage</h3> <pre> .Call(.NAME, ..., PACKAGE) .External(.NAME, ..., PACKAGE) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>.NAME</code></td> <td> <p>a character string giving the name of a C function, or an object of class <code>"<a href="getNativeSymbolInfo.html">NativeSymbolInfo</a>"</code>, <code>"<a href="getNativeSymbolInfo.html">RegisteredNativeSymbol</a>"</code> or <code>"<a href="getNativeSymbolInfo.html">NativeSymbol</a>"</code> referring to such a name.</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>arguments to be passed to the compiled code. Up to 65 for <code>.Call</code>.</p> </td></tr> <tr valign="top"><td><code>PACKAGE</code></td> <td> <p>if supplied, confine the search for a character string <code>.NAME</code> to the DLL given by this argument (plus the conventional extension, ‘<span class="file">.so</span>’, ‘<span class="file">.dll</span>’, ...). </p> <p>This argument follows <code>...</code> and so its name cannot be abbreviated. </p> <p>This is intended to add safety for packages, which can ensure by using this argument that no other package can override their external symbols, and also speeds up the search (see ‘Note’).</p> </td></tr> </table> <h3>Details</h3> <p>The functions are used to call compiled code which makes use of internal <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> objects, passing the arguments to the code as a sequence of <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> objects. They assume C calling conventions, so can usually also be used for C++ code. </p> <p>For details about how to write code to use with these functions see the chapter on ‘System and foreign language interfaces’ in the ‘Writing <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> Extensions’ manual. They differ in the way the arguments are passed to the C code: <code>.External</code> allows for a variable or unlimited number of arguments. </p> <p>These functions are <a href="Primitive.html">primitive</a>, and <code>.NAME</code> is always matched to the first argument supplied (which should not be named). For clarity, avoid using names in the arguments passed to <code>...</code> that match or partially match <code>.NAME</code>. </p> <h3>Value</h3> <p>An <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> object constructed in the compiled code. </p> <h3>Header files for external code</h3> <p>Writing code for use with these functions will need to use internal <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> structures defined in ‘<span class="file">Rinternals.h</span>’ and/or the macros in ‘<span class="file">Rdefines.h</span>’. </p> <h3>Note</h3> <p>If one of these functions is to be used frequently, do specify <code>PACKAGE</code> (to confine the search to a single DLL) or pass <code>.NAME</code> as one of the native symbol objects. Searching for symbols can take a long time, especially when many namespaces are loaded. </p> <p>You may see <code>PACKAGE = "base"</code> for symbols linked into <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span>. Do not use this in your own code: such symbols are not part of the API and may be changed without warning. </p> <p><code>PACKAGE = ""</code> used to be accepted (but was undocumented): it is now an error. </p> <h3>References</h3> <p>Chambers, J. M. (1998) <em>Programming with Data. A Guide to the S Language</em>. Springer. (<code>.Call</code>.) </p> <h3>See Also</h3> <p><code><a href="dynload.html">dyn.load</a></code>, <code><a href="Foreign.html">.C</a></code>, <code><a href="Foreign.html">.Fortran</a></code>. </p> <p>The ‘Writing R Extensions’ manual. </p> <hr /><div style="text-align: center;">[Package <em>base</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>