library.dynam {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 (‘`.dll`’ on Windows) 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`). Versions of R prior to 2.1.0 simply recorded the (names of) packages which had loaded shared libraries. Versions of R prior to 1.6.0 used an internal global variable `.Dyn.libs` for storing this information: this variable is now defunct.

### 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 specifed, an object of class `"DLLInfo"` that identifies the DLL and can be used in future calls is returned invisibly. For packages that have namespaces, a list of these objects is stored in the namespace'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 DLLs.

### Examples

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

[Package base version 2.3.1 Index]