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 _a _n_a_t_i_v_e (_C/_F_o_r_t_r_a_n) _s_y_m_b_o_l

_D_e_s_c_r_i_p_t_i_o_n:

     This finds and returns as comprehensive a description of a
     dynamically loaded or "exported" built-in native symbol. 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.

_U_s_a_g_e:

     getNativeSymbolInfo(name, PACKAGE)

_A_r_g_u_m_e_n_t_s:

    name: the name of the native symbol 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 dynamically
          loaded library we restrict the search for this symbol. If
          this is '"base"', we search in the R executable itself.

_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 shared library 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:

     If the symbol is not found, an error is raised. Otherwise, the
     value is a list containing the following elements: 

    name: the name of the symbol, as given by the 'name' argument.

 address: the native memory address of the symbol which can be used to
          invoke the routine, and also compare with other symbol
          address. This is an external pointer object and of class
          'NativeSymbol'.

 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 shared library file.

          _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.

_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

