getNativeSymbolInfo
Obtain a Description of one or more Native (C/Fortran) Symbols
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 .Call
,
.C
, .Fortran
, or
.External
). 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.
- Keywords
- interface
Usage
getNativeSymbolInfo(name, PACKAGE, unlist = TRUE,
withRegistrationInfo = FALSE)
Arguments
- name
the name(s) of the native symbol(s).
- PACKAGE
an optional argument that specifies to which DLL to 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
isTRUE
and the number of symbol names inname
is one, then theNativeSymbolInfo
object is returned. If it isFALSE
, then a list ofNativeSymbolInfo
objects is returned. This is ignored if the number of symbols passed inname
is more than one. To be compatible with earlier versions of this function, this defaults toTRUE
.- 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 ifFALSE
to return just the address of the symbol.
Details
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.
Value
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:
the name of the symbol, as given by the
name
argument.
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
.
a list containing 3 elements:
- name
the short form of the library name which can be used as the value of the
PACKAGE
argument in the different native interface functions.- path
the fully qualified name of the DLL.
- dynamicLookup
a logical value indicating whether dynamic resolution is used when looking for symbols in this library, or only registered routines can be located.
the number of arguments that should be passed in a call to this routine.
If any of the symbols is not found, an error is 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.
Note
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.
References
For information about registering native routines, see “In Search of C/C++ & FORTRAN Routines”, R-News, volume 1, number 3, 2001, p20--23 (https://www.r-project.org/doc/Rnews/Rnews_2001-3.pdf).
See Also
getDLLRegisteredRoutines
,
is.loaded
,
.C
,
.Fortran
,
.External
,
.Call
,
dyn.load
.