library.dynam              package:base              R Documentation

_L_o_a_d_i_n_g _D_L_L_s _f_r_o_m _P_a_c_k_a_g_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     Load the specified file of compiled code if it has not been loaded
     already, or unloads it.

_U_s_a_g_e:

     library.dynam(chname, package = NULL, lib.loc = NULL,
                   verbose = getOption("verbose"),
                   file.ext = .Platform$dynlib.ext, ...)

     library.dynam.unload(chname, libpath,
                   verbose = getOption("verbose"),
                   file.ext = .Platform$dynlib.ext)

     .dynLibs(new)

_A_r_g_u_m_e_n_t_s:

  chname: a character string naming a DLL (also known as a dynamic
          shared object or library) to load.

 package: a character vector with the names of packages to search
          through, or 'NULL'.  By default, all packages in the search
          path are used.

 lib.loc: a character vector describing the location of R library trees
          to search through, or 'NULL'.  The default value of 'NULL'
          corresponds to all libraries currently known.

 libpath: the path to the loaded package whose DLL is to be unloaded.

 verbose: a logical value indicating whether an announcement is printed
          on the console before loading the DLL.  The default value is
          taken from the verbose entry in the system 'options'.

file.ext: the extension (including '.' if used) to append to the file
          name to specify the library to be loaded.  This defaults to
          the appropriate value for the operatingsystem.

     ...: additional arguments needed by some libraries that are passed
          to the call to 'dyn.load' to control how the library and its
          dependencies are loaded.

     new: a list of '"DLLInfo"' objects corresponding to the DLLs
          loaded by packages.  Can be missing.

_D_e_t_a_i_l_s:

     See 'dyn.load' for what sort of objects these functions handle.

     'library.dynam' is designed to be used inside a package rather
     than at the command line, and should really only be used inside
     '.First.lib' or '.onLoad'.  The system-specific extension for DLLs
     (e.g., '.so' or '.sl' on Unix systems, '.so' on Mac OS X, '.dll'
     on Windows) should not be added.

     'library.dynam.unload' is designed for use in '.Last.lib' or
     '.onUnload': it unloads the DLL and updates the value of
     '.dynLibs()'

     '.dynLibs' is used for getting (with no argument) or setting the
     DLLs which are currently loaded by packages (using
     'library.dynam').

_V_a_l_u_e:

     If 'chname' is not specified, 'library.dynam' returns an object of
     class '"DLLInfoList"' corresponding to the DLLs loaded by
     packages.

     If 'chname' is specified, an object of class '"DLLInfo"' that
     identifies the DLL and can be used in future calls is returned
     invisibly.  For packages that have name spaces, a list of these
     objects is stored in the name space's environment for use at
     run-time.

     Note that the class 'DLLInfo' has an overloaded method for '$'
     which can be used to resolve native symbols within that DLL.

     'library.dynam.unload' invisibly returns an object of class
     '"DLLInfo"' identifying the DLL successfully unloaded.

     '.dynLibs' returns an object of class '"DLLInfoList"'
     corresponding corresponding to its current value.

_W_a_r_n_i_n_g:

     Do not use 'dyn.unload' on a DLL loaded by 'library.dynam': use
     'library.dynam.unload' to ensure that '.dynLibs' gets updated. 
     Otherwise a subsequent call to 'library.dynam' will be told the
     object is already loaded.

     Note that whether or not it is possible to unload a DLL and then
     reload a revised version of the same file is OS-dependent: see the
     'Value' section of the help for  'dyn.unload'.

_R_e_f_e_r_e_n_c_e_s:

     Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) _The New S
     Language_. Wadsworth & Brooks/Cole.

_S_e_e _A_l_s_o:

     'getLoadedDLLs' for information on '"DLLInfo"' and '"DLLInfoList"'
     objects.

     '.First.lib', 'library', 'dyn.load', '.packages', '.libPaths'

     'SHLIB' for how to create suitable DLLs.

_E_x_a_m_p_l_e_s:

     ## Which DLLs were "dynamically loaded" by packages?
     library.dynam()