dyn.load {base} | R Documentation

## Foreign Function Interface

### Description

Load or unload shared libraries, and test whether a C function or Fortran subroutine is available.

### Usage

    dyn.load(x, local = TRUE, now = TRUE)
    dyn.unload(x)

    is.loaded(symbol, PACKAGE = "", type = "")
    symbol.C(name)
    symbol.For(name)

### Arguments

`x` | a character string giving the pathname to a shared library or DLL.
`local` | a logical value controlling whether the symbols in the shared library are stored in their own local table and not shared across shared libraries, or added to the global symbol table. Whether this has any effect is system-dependent. It is ignored on Windows.
`now` | a logical controlling whether all symbols are resolved (and relocated) immediately the library is loaded or deferred until they are used. This control is useful for developers testing whether a library is complete and has all the necessary symbols, and for users to ignore missing symbols. Whether this has any effect is system-dependent. It is ignored on Windows.
`symbol` | a character string giving a symbol name.
`PACKAGE` | if supplied, confine the search for the `name` to the DLL given by this argument (plus the conventional extension, `.so`, `.sl`, `.dll`, ...). This is intended to add safety for packages, which can ensure by using this argument that no other package can override their external symbols. Use `PACKAGE="base"` for symbols linked in to R. This is used in the same way as in `.C`, `.Call`, `.Fortran` and `.External` functions
`name` | a character string giving either the name of a C function or Fortran subroutine. Fortran names probably need to be given entirely in lower case (but this may be system-dependent).
`type` | The type of symbol to look for: can be any (`""`, the default), `"Fortran"`, `"Call"` or `"External"`.

### Details

See ‘See Also’ and the Writing R Extensions and R Installation and Administration manuals for how to create and install a suitable shared library. Note that unlike some versions of S-PLUS, `dyn.load` does not load an object (`.o`) file but a shared library or DLL.

Unfortunately a very few platforms (Compaq Tru64) do not handle the `PACKAGE` argument correctly, and may incorrectly find symbols linked into R.

The additional arguments to `dyn.load` mirror the different aspects of the mode argument to the dlopen() routine on UNIX systems. They are available so that users can exercise greater control over the loading process for an individual library. In general, the defaults values are appropriate and you should override them only if there is good reason and you understand the implications.

External code must not change the floating point control word, but many DLLs do so. Common changes are to set it to use 53 bit precision instead of R's default 64 bit precision, or to unmask some exceptions. `dyn.load` detects such changes, and restores R's control word to its default value of hex 8001F. This may cause the DLL to malfunction; if so, it should be rewritten to save and restore the control word itself. If `warn.FPU` is set to `TRUE` using the `options` function, a warning will be printed. (If the warning says that the control word was changed from some other value than 8001F, please report the circumstances to the Windows maintainers: that probably indicates an internal bug.)

### Value

The function `dyn.load` is used for its side effect which links the specified shared library to the executing R image. Calls to `.C`, `.Call`, `.Fortran` and `.External` can then be used to execute compiled C functions or Fortran subroutines contained in the library. The return value of `dyn.load` is an object of class `DLLInfo`. See `getLoadedDLLs` for information about this class.
The function `dyn.unload` unlinks the shared library.
Functions `symbol.C` and `symbol.For` are for historical compatibility with S. `symbol.C` just returns its argument unchanged, whereas `symbol.For` will append an underscore on those platforms (almost all) which do so for Fortran symbols. These are no longer of much use in R.
`is.loaded` checks if the symbol name is loaded and hence available for use in `.C` or `.Fortran` or `.Call` or `.Exernal`: it requires the name you would give to `.C` etc and not that remapped by `symbol.C` or `symbol.For`. It will succeed if any one of the four calling functions would succeed in using the entry point unless `type` is specified: for Fortran entry points `is.loaded(symbol.For("symbol"))` will also succeed unless the registration mechanism has been used.

### Warning

Do not use `dyn.unload` on a shared object loaded by `library.dynam`: use `library.dynam.unload`.

### Note

The creation of shared libraries and the runtime linking of them into executing programs is very platform dependent. In recent years there has been some simplification in the process because the C subroutine call `dlopen` has become the standard for doing this under UNIX. Under UNIX `dyn.load` uses the `dlopen` mechanism and should work on all platforms which support it. On Windows it uses the standard mechanisms for loading 32-bit DLLs.

The original code for loading DLLs in UNIX was provided by Heiner Schwarte. The compatibility code for HP-UX was provided by Luke Tierney.

### References

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

### See Also

`library.dynam` to be used inside a package's `.First.lib` initialization.

`SHLIB` for how to create suitable DLLs.

`.C`, `.Fortran`, `.External`, `.Call`.

### Examples

    is.loaded("hcass2") #-> probably TRUE, as stats is loaded
    is.loaded("supsmu") # Fortran entry point in stats
    is.loaded("supsmu", "stats", "Fortran")
    is.loaded("PDF", type = "External")

[Package base version 2.3.1 Index]