getNativeSymbolInfo
Obtain a Description of one or more Native Symbols
Description
Returns the specified native symbol information.
Usage
getNativeSymbolInfo(name, PACKAGE, unlist = TRUE,
withRegistrationInfo = FALSE)
Arguments
| name |
a vector or list of names, or a "NativeRoutineList" object specifying
native functions to get information for.
|
| PACKAGE |
a package name, "DLLInfo" or "DllInfoReference" object specifying the package
the search for functions should be constrained to.
|
| unlist |
a logical flag. If TRUE, the return value is unlisted for single symbol information.
Otherwise, a list contained one or more symbols information is returned.
|
| withRegistrationInfo |
a logical flag. If TRUE, indicates that the function entry point is returned.
If FALSE (the default), its registration address is returned.
|
Details
This function searches for external functions (optionally constrained by the specified package)
and returns a list of structures (one per function) containing the following:
- The function name.
- Its entry point address.
- Information about the DLL in which it resides (as an object of type "DLLInfo").
- The number of function arguments (if known).
- The interface by which it should be called (if known).
If the function was registered explicitly with the engine (via the
R_registerRoutines API)
rather than dynamically resolved, and if the
withRegistrationInfo
argument is
TRUE, then that information is also passed back.
Value
returns a named list with function information. Each element is a list of class
"NativeSymbolInfo",
which is for registered symbols combined with one class of
"CRoutine",
"CallRoutine",
"FortranRoutine", or
"ExternalRoutine", depending on the call type registered. This list
contains the following components:
| name |
a character string representing the function name.
|
| address |
Logical NA of either class "NativeSymbol" or "RegisteredNativeSymbol" for registered functions
when the withRegistrationInfo argument is TRUE.
|
| dll |
a "DLLInfo" object describing the DLL that contains the function.
|
| numParameters |
the number of function arguments, or NA if it was not set at registration time, or if the
function was not registered.
|
Differences between TIBCO Enterprise Runtime for R and Open-source R
In open-source R, getNativeSymbolInfo returns the address of the routine's entry point or its registration record
(if withRegistrationInfo is TRUE) in the address field. In TIBCO Enterprise Runtime for R, the field always
contains NA. The name of the third field of the return value is a package in open-source R, but it is a DLL in TIBCO Enterprise Runtime for R,
where it is compatible with information returned by getDLLRegisteredRoutines (where open-source R names the field DLL).
References
Lang, D. T. 2001. In Search of C/C++ & FORTRAN Routines. R News. Volume 1/3, pages 20-23, September 2001.
See Also
Examples
library(nlme)
getNativeSymbolInfo(c("fit_gnls","mixed_EM"), "nlme")
getNativeSymbolInfo(c("fit_gnls","mixed_EM"), getLoadedDLLs()$nlme) # PACKAGE is a "DLLInfo" object.
identical(getNativeSymbolInfo("fit_gnls"), getLoadedDLLs()$nlme$fit_gnls) # TRUE
getNativeSymbolInfo("fit_gnls", "nlme", unlist = FALSE) # result for single symbol is unlisted.
getNativeSymbolInfo("fit_gnls", "nlme")$address # class: "NativeSymbol"
getNativeSymbolInfo("fit_gnls", "nlme", withRegistrationInfo = TRUE)$address # class: "RegisteredNativeSymbol"