EVOLUTION-MANAGER
Edit File: getNativeSymbolInfo.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: Obtain a Description of one or more Native (C/Fortran)...</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 getNativeSymbolInfo {base}"><tr><td>getNativeSymbolInfo {base}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2> Obtain a Description of one or more Native (C/Fortran) Symbols </h2> <h3>Description</h3> <p>This finds and returns a description of one or more dynamically loaded or ‘exported’ built-in native symbols. For each name, it returns information about the name of the symbol, the library in which it is located and, if available, the number of arguments it expects and by which interface it should be called (i.e <code><a href="CallExternal.html">.Call</a></code>, <code><a href="Foreign.html">.C</a></code>, <code><a href="Foreign.html">.Fortran</a></code>, or <code><a href="CallExternal.html">.External</a></code>). Additionally, it returns the address of the symbol and this can be passed to other C routines. Specifically, this provides a way to explicitly share symbols between different dynamically loaded package libraries. Also, it provides a way to query where symbols were resolved, and aids diagnosing strange behavior associated with dynamic resolution. </p> <h3>Usage</h3> <pre> getNativeSymbolInfo(name, PACKAGE, unlist = TRUE, withRegistrationInfo = FALSE) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>name</code></td> <td> <p>the name(s) of the native symbol(s).</p> </td></tr> <tr valign="top"><td><code>PACKAGE</code></td> <td> <p>an optional argument that specifies to which DLL to restrict the search for this symbol. If this is <code>"base"</code>, we search in the <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> executable itself.</p> </td></tr> <tr valign="top"><td><code>unlist</code></td> <td> <p>a logical value which controls how the result is returned if the function is called with the name of a single symbol. If <code>unlist</code> is <code>TRUE</code> and the number of symbol names in <code>name</code> is one, then the <code>NativeSymbolInfo</code> object is returned. If it is <code>FALSE</code>, then a list of <code>NativeSymbolInfo</code> objects is returned. This is ignored if the number of symbols passed in <code>name</code> is more than one. To be compatible with earlier versions of this function, this defaults to <code>TRUE</code>. </p> </td></tr> <tr valign="top"><td><code>withRegistrationInfo</code></td> <td> <p>a logical value indicating whether, if <code>TRUE</code>, to return information that was registered with <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> about the symbol and its parameter types if such information is available, or if <code>FALSE</code> to return just the address of the symbol. </p> </td></tr> </table> <h3>Details</h3> <p>This uses the same mechanism for resolving symbols as is used in all the native interfaces (<code><a href="CallExternal.html">.Call</a></code>, etc.). If the symbol has been explicitly registered by the DLL in which it is contained, information about the number of arguments and the interface by which it should be called will be returned. Otherwise, a generic native symbol object is returned. </p> <h3>Value</h3> <p>Generally, a list of <code>NativeSymbolInfo</code> elements whose elements can be indexed by the elements of <code>name</code> in the call. Each <code>NativeSymbolInfo</code> object is a list containing the following elements: </p> <table summary="R valueblock"> <tr valign="top"><td><code>name</code></td> <td> <p>the name of the symbol, as given by the <code>name</code> argument.</p> </td></tr> <tr valign="top"><td><code>address</code></td> <td> <p>if <code>withRegistrationInfo</code> is <code>FALSE</code>, this is the native memory address of the symbol which can be used to invoke the routine, and also to compare with other symbol addresses. This is an external pointer object and of class <code>NativeSymbol</code>. If <code>withRegistrationInfo</code> is <code>TRUE</code> and registration information is available for the symbol, then this is an object of class <code>RegisteredNativeSymbol</code> and is a reference to an internal data type that has access to the routine pointer and registration information. This too can be used in calls to <code><a href="CallExternal.html">.Call</a></code>, <code><a href="Foreign.html">.C</a></code>, <code><a href="Foreign.html">.Fortran</a></code> and <code><a href="CallExternal.html">.External</a></code>. </p> </td></tr> <tr valign="top"><td><code>dll</code></td> <td> <p>a list containing 3 elements: </p> <dl> <dt>name</dt><dd><p>the short form of the library name which can be used as the value of the <code>PACKAGE</code> argument in the different native interface functions.</p> </dd> <dt>path</dt><dd><p>the fully qualified name of the DLL.</p> </dd> <dt>dynamicLookup</dt><dd><p>a logical value indicating whether dynamic resolution is used when looking for symbols in this library, or only registered routines can be located.</p> </dd> </dl> </td></tr> </table> <p>If the routine was explicitly registered by the dynamically loaded library, the list contains a fourth field </p> <table summary="R valueblock"> <tr valign="top"><td><code>numParameters</code></td> <td> <p>the number of arguments that should be passed in a call to this routine.</p> </td></tr> </table> <p>Additionally, the list will have an additional class, being <code>CRoutine</code>, <code>CallRoutine</code>, <code>FortranRoutine</code> or <code>ExternalRoutine</code> corresponding to the R interface by which it should be invoked. </p> <p>If any of the symbols is not found, an error is raised. </p> <p>If <code>name</code> contains only one symbol name and <code>unlist</code> is <code>TRUE</code>, then the single <code>NativeSymbolInfo</code> is returned rather than the list containing that one element. </p> <h3>Note</h3> <p>The third element of the <code>NativeSymbolInfo</code> objects was renamed from <code>package</code> to <code>dll</code> in <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> version 3.6.0, for consistency with the names of the <code>NativeSymbolInfo</code> objects returned by <code><a href="getDLLRegisteredRoutines.html">getDLLRegisteredRoutines</a>()</code>. </p> <h3>Note</h3> <p>One motivation for accessing this reflectance information is to be able to pass native routines to C routines as function pointers in C. This allows us to treat native routines and <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> functions in a similar manner, such as when passing an <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> function to C code that makes callbacks to that function at different points in its computation (e.g., <code><a href="../../stats/html/nls.html">nls</a></code>). Additionally, we can resolve the symbol just once and avoid resolving it repeatedly or using the internal cache. </p> <h3>Author(s)</h3> <p>Duncan Temple Lang</p> <h3>References</h3> <p>For information about registering native routines, see “In Search of C/C++ & FORTRAN Routines”, R-News, volume 1, number 3, 2001, p20–23 (<a href="https://www.r-project.org/doc/Rnews/Rnews_2001-3.pdf">https://www.r-project.org/doc/Rnews/Rnews_2001-3.pdf</a>). </p> <h3>See Also</h3> <p><code><a href="getDLLRegisteredRoutines.html">getDLLRegisteredRoutines</a></code>, <code><a href="dynload.html">is.loaded</a></code>, <code><a href="Foreign.html">.C</a></code>, <code><a href="Foreign.html">.Fortran</a></code>, <code><a href="CallExternal.html">.External</a></code>, <code><a href="CallExternal.html">.Call</a></code>, <code><a href="dynload.html">dyn.load</a></code>. </p> <hr /><div style="text-align: center;">[Package <em>base</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>