getDLLRegisteredRoutines        package:base        R Documentation

Reflectance Information for C/Fortran routines in a DLL

Description:

     This function allows us to query the set of routines in a DLL that
     are registered with R to enhance dynamic lookup, error handling
     when calling native routines, and potentially security in the
     future. This function provides a description of each of the
     registered routines in the DLL for the different interfaces, i.e.
     '.C', '.Call', '.Fortran' and '.External'.

Usage:

     getDLLRegisteredRoutines(dll, addNames = TRUE)

Arguments:

     dll: a character string or 'DLLInfo' object. The character string
          specifies the file name of the DLL of interest, and is given
          without the file name extension (e.g., the '.dll' or '.so')
          and with no directory/path information. So a file
          'MyPackage/libs/MyPackage.so' would be specified as
          'MyPackage'.

          The 'DLLInfo' objects can be obtained directly in calls to
          'dyn.load' and  'library.dynam', or can be found after the
          DLL has been loaded using 'getLoadedDLLs', which returns a
          list of 'DLLInfo' objects (index-able by DLL file name).

          The 'DLLInfo' approach avoids any ambiguities related to two
          DLLs having the same name but corresponding to files in
          different directories. 

addNames: a logical value. If this is 'TRUE', the elements of the
          returned lists are named using the names of the routines (as
          seen by R via registration or raw name).  If 'FALSE', these
          names are not computed and assigned to the lists.  As a
          result, the call should be quicker.  The name information is
          also available in the 'NativeSymbolInfo' objects in the
          lists. 

Details:

     This takes the registration information after it has been
     registered and processed by the R internals. In other words, it
     uses the extended information

Value:

     A list with four elements corresponding to the routines registered
     for the .C, .Call, .Fortran and .External interfaces. Each element
     is a list with as many elements as there were routines registered
     for that interface. Each element identifies a routine and is an
     object of class 'NativeSymbolInfo'. An object of this class has
     the following fields: 

    name: the registered name of the routine (not necessarily the name
          in the C code).

 address: the memory address of the routine as resolved in the loaded
          DLL. This may be 'NULL' if the symbol has not yet been
          resolved.

     dll: an object of class 'DLLInfo' describing the DLL. This is same
          for all elements returned.

numParameters: the number of arguments the native routine is to be
          called with. In the future, we will provide information about
          the types of the parameters also. 

Author(s):

     Duncan Temple Lang <duncan@wald.ucdavis.edu>

References:

     "Writing R Extensions Manual" for symbol registration. R News,
     Volume 1/3, September 2001.   "In search of C/C++ & Fortran
     Symbols"

See Also:

     'getLoadedDLLs'

Examples:

     dlls <- getLoadedDLLs()
     getDLLRegisteredRoutines(dlls[["base"]])

     getDLLRegisteredRoutines("stats")

