dynbind               package:rdyncall               R Documentation

_D_y_n_a_m_i_c _b_i_n_d_i_n_g_s _t_o _s_h_a_r_e_d _l_i_b_r_a_r_i_e_s.

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

     Function to create dynamic bindings to shared libraries.

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

     dynbind(libname, libsignature, envir=parent.frame(), callmode="cdecl", pat=NULL, replace=NULL, funcptr=FALSE)

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

 libname: A character string specifying the short library name or path.

libsignature: A character string specifying function symbol names and
          type signatures.

   envir: An environment where the binding functions are installed.

callmode: A character string specifying the calling convention of the
          target library.

     pat: NULL or a regular expression character string that will match
          and which will be replaced by 'pat'

 replace: NULL or a regular expression character string to replace
          'pat'

 funcptr: A logical specifying if symbols represent function pointer
          variables instead of functions.

_D_e_t_a_i_l_s:

     The function loads the library specified by 'libname' and resolves
     compiled code   specified by 'libsignature'. For each successfully
     resolved function, a R wrapper function will be created and
     installed in the environment 'envir'.

     The location of the library can be specified by a absolut system
     file-path or using a short name.

     When using a short name, the library is looked up using the 'PATH'
     environment variable. from a shared library to the R process at
     run-time.

     The 'libname' character string specifies the location of the
     library. 

     The library is specified by 'libname' given as a character string
     either in short or  long form (absolute file path).

     If 'libname' specifies only a short form - where only the library
     name itself is given.

     The 'libname' specified by 'libsignature' to  the R process. For
     each C function and binds C functions specified by the
     'lib.signature'.

     In the short form, the function tries to locate the library at
     well known places. does not contain a full path or
     platform-specific prefix and suffixes. 'dynbind' will look for the
     library in certain places using the 'PATH' system environment
     variable  on Windows and Posix.

     probably surrounded by platform-specific prefixes and suffixes.
     'dynbind' will look for several alternatives. In some cases, a
     platform-specific specification must be done by the user, e.g. the
     OpenGL library is available as OPENGL32.DLL on windows, while on
     unix it is available as libGL.so and on Mac OS X the library is
     living in a specific place
     '/System/Library/Frameworks/OpenGL.framework/Libraries/libGL.dylib'.

       *Platform*  *Filename extension*  *Variants*
       Windows     'dll'                 '"'_name_'.dll"' or '"lib'_name_'.dll"'
       Unix        'so'                  '"lib'_name_'.so"'
       Mac OS X    'dylib'               '"lib'_name_'.dylib"'

     The 'lib.signature' character string contains a list of
     full-qualified function symbol and signature separated by '';''
     (semicolon) character. White spaces, tabs and new-line characters
     are ignored. Each function binding consists of

       _function-name_ ''('' _argument-types_ '')'' _return-type_ '';''

     The following example binds four C functions from the R run-time
     to R. Note that  this binding is not possible with .C binding.  

     #preformatted{ /* C function prototypes from R run-time shared
     library */ void R_isort (int* x, int n); void R_rsort (double* x,
     int n); void R_csort (Rcomplex* x, int n); void rsort_with_index
     (double* x, int* index, int n);

     # Dynamic bindings in R using dynbind:

     dynbind("R", "R_isort(pi)v; R_rsort(pi)v; R_csort(pi)v;
     rsort_with_index(ppi)v;")

     # Now, R_isort, R_rsort, R_csort, rsort_with_index are ready to
     use:

     x <- as.integer( rnorm(100)*100 ) R_isort(x,length(x))

     }

     _function-name_ ''('' _call-signature_ '';'' 

_S_e_e _A_l_s_o:

     '.dyncall'.

