library.dynam              package:base              R Documentation

Loading Shared Libraries

Description:

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

Usage:

     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)

Arguments:

  chname: a character string naming a shared 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 shared library is to be
          unloaded.

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

file.ext: the extension to append to the file name to specify the
          library to be loaded. This defaults to the appropriate value
          for the operating system.

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

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

Details:

     '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
     shared libraries (e.g., '.so' or '.sl' on Unix systems) should not
     be added.  Note that to allow for versioned installs, the 'chname'
     argument should not be set to the 'pkgname' argument of
     '.First.lib' or '.onLoad'.

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

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

Value:

     If 'chname' is not specified, 'library.dynam' returns an object of
     class '"DLLInfoList"' corresponding to the shared libraries 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.

Warning:

     Do not use 'dyn.unload' on a shared object 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.

References:

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

See Also:

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

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

     'SHLIB' for how to create suitable shared libraries.

Examples:

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

