getNativeSymbolInfo           package:base           R Documentation

_O_b_t_a_i_n _a _D_e_s_c_r_i_p_t_i_o_n _o_f _o_n_e _o_r _m_o_r_e _N_a_t_i_v_e (_C/_F_o_r_t_r_a_n) _S_y_m_b_o_l_s

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

     getNativeSymbolInfo(name, PACKAGE, unlist = TRUE,
                         withRegistrationInfo = FALSE)

_A_r_g_u_m_e_n_t_s:

    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. 

_D_e_t_a_i_l_s:

     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.

_V_a_l_u_e:

     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:

          _n_a_m_e the short form of the library name which can be used as
               the value of the 'PACKAGE' argument in the different
               native interface functions.

          _p_a_t_h the fully qualified name of the DLL.

          _d_y_n_a_m_i_c_L_o_o_k_u_p a logical value indicating whether dynamic
               resolution is used when looking for symbols in this
               library, or only registered routines can be located.

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.

_N_o_t_e:

     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.

_A_u_t_h_o_r(_s):

     Duncan Temple Lang

_R_e_f_e_r_e_n_c_e_s:

     For information about registering native routines, see "In Search
     of C/C++ & FORTRAN Routines", R-News, volume 1, number 3, 2001,
     p20-23 (<URL: http://CRAN.R-project.org/doc/Rnews/>).

_S_e_e _A_l_s_o:

     'getDLLRegisteredRoutines', 'is.loaded', '.C', '.Fortran',
     '.External', '.Call', 'dyn.load'.

_E_x_a_m_p_l_e_s:

     library(stats) # normally loaded
     getNativeSymbolInfo("dansari")

     getNativeSymbolInfo("hcass2")  # a Fortran symbol