R: Loading DLLs from Packages

library.dynam {base} | R Documentation

## Loading DLLs from Packages

### Description

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

### Usage

    library.dynam(chname, package, lib.loc,
                  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 DLL (also known as a dynamic shared object or library) to load.
`package` | a character vector with the name of package.
`lib.loc` | a character vector describing the location of R library trees to search through.
`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 operating system.
`...` | 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.

### Details

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 `.onLoad`. The system-specific extension for DLLs (e.g., ‘.so’ or ‘.sl’ on Unix-alike systems, ‘.dll’ on Windows) should not be added.

If `...` does not include a named argument `DLLpath`, `dyn.load` is called with `DLLpath` set to the package's ‘libs’ directory. See the “Windows” section of the help on `dyn.load` for how to control where dependent DLLs are found.

See `dyn.load` for comments about diagnostic messages which may be seen on Windows.

`library.dynam.unload` is designed for use in `.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`).

### Value

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 which can be used in future calls is returned invisibly. Note that the class `"DLLInfo"` has a 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 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`.

### 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.

`.onLoad`, `library`, `dyn.load`, `.packages`, `.libPaths`

`SHLIB` for how to create suitable DLLs.

### Examples

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

    ## More on library.dynam.unload() :
    require(nlme)
    nlme:::.onUnload # shows library.dynam.unload() call
    detach("package:nlme")  # by default, unload=FALSE ,  so,
    tail(library.dynam(), 2)# nlme still there

    ## How to unload the DLL ?
    ## Best is to unload the namespace,  unloadNamespace("nlme")
    ## If we need to do it separately which should be exceptional:
    pd.file <- attr(packageDescription("nlme"), "file")
    library.dynam.unload("nlme", libpath = sub("/Meta.*", '', pd.file))
    tail(library.dynam(), 2)# 'nlme' is gone now
    unloadNamespace("nlme") # now gives warning

[Package base version 3.5.1 Index]