getNativeSymbolInfo {base} | R Documentation |
This finds and returns as comprehensive 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
.Call
, .C
, .Fortran
, or
.External
). Additionally, it returns the address of the
symbol and this can be passed to other C routines which can
invoke. 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.
This is vectorized in the name
argument so can process
multiple symbols in a single call. The result is a list that can be
indexed by the given symbol names.
getNativeSymbolInfo(name, PACKAGE, unlist = TRUE, withRegistrationInfo = FALSE)
name |
the name(s) of the native symbol(s) as used in a call
to is.loaded , etc. Note that Fortran symbols should be
supplied as-is, not wrapped in symbol.For .
|
PACKAGE |
an optional argument that specifies to which
DLL we restrict the search for this symbol. If this is
"base" , we search in the R executable itself. |
unlist |
a logical value which controls how the result is
returned if the function is called with the name of a single symbol.
If unlist is TRUE and the number of symbol names in
name is one, then the NativeSymbolInfo object
is returned. If it is FALSE , then a list
of NativeSymbolInfo objects is returned.
This is ignored if the number of symbols passed in name is
more than one.
To be compatible with earlier versions of this function, this
defaults to TRUE .
|
withRegistrationInfo |
a logical value indicating whether, if
TRUE , to return information that was registered with R about
the symbol and its parameter types if such information is available,
or if FALSE to return the address of the symbol.
|
This uses the same mechanism for resolving symbols as is used
in all the native interfaces (.Call
, 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.
Generally, a list of NativeSymbolInfo
elements whose elements
can be indexed by the elements of name
in the call. Each
NativeSymbolInfo
object is a list containing the following
elements:
name |
the name of the symbol, as given by the
name argument. |
address |
if withRegistrationInfo is FALSE ,
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 NativeSymbol .
If withRegistrationInfo is TRUE and registration
information is available for the symbol, then this is
an object of class RegisteredNativeSymbol 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
.Call , .C , .Fortran and
.External .
|
package |
a list containing 3 elements:
|
numParameters |
the number of arguments that should be passed in a call to this routine. |
Additionally, the list will have an additional class,
being CRoutine
, CallRoutine
, FortranRoutine
or
ExternalRoutine
corresponding to the R interface by which it
should be invoked.
If any of the symbols is not found, an error is immediately raised.
If name
contains only one symbol name and unlist
is
TRUE
, then the single NativeSymbolInfo
is returned
rather than the list containing that one element.
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 R functions in a similar
manner, such as when passing an R function to C code that makes
callbacks to that function at different points in its computation
(e.g., nls
). Additionally, we can resolve the symbol
just once and avoid resolving it repeatedly or using the internal
cache. In the future, one may be able to treat NativeSymbol
objects directly as callback objects.
Duncan Temple Lang
For information about registering native routines, see “In Search of C/C++ & FORTRAN Routines”, R-News, volume 1, number 3, 2001, p20–23 (http://CRAN.R-project.org/doc/Rnews/).
getDLLRegisteredRoutines
,
is.loaded
,
.C
,
.Fortran
,
.External
,
.Call
,
dyn.load
.
library(stats) # normally loaded getNativeSymbolInfo("dansari") getNativeSymbolInfo("hcass2") # a Fortran symbol