EVOLUTION-MANAGER
Edit File: dynload.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Foreign Function Interface</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for dyn.load {base}"><tr><td>dyn.load {base}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Foreign Function Interface</h2> <h3>Description</h3> <p>Load or unload DLLs (also known as shared objects), and test whether a C function or Fortran subroutine is available. </p> <h3>Usage</h3> <pre> dyn.load(x, local = TRUE, now = TRUE, ...) dyn.unload(x) is.loaded(symbol, PACKAGE = "", type = "") </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>x</code></td> <td> <p>a character string giving the pathname to a DLL, also known as a dynamic shared object. (See ‘Details’ for what these terms mean.)</p> </td></tr> <tr valign="top"><td><code>local</code></td> <td> <p>a logical value controlling whether the symbols in the DLL are stored in their own local table and not shared across DLLs, or added to the global symbol table. Whether this has any effect is system-dependent. </p> </td></tr> <tr valign="top"><td><code>now</code></td> <td> <p>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. </p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>other arguments for future expansion. </p> </td></tr> <tr valign="top"><td><code>symbol</code></td> <td> <p>a character string giving a symbol name.</p> </td></tr> <tr valign="top"><td><code>PACKAGE</code></td> <td> <p>if supplied, confine the search for the <code>name</code> to the DLL given by this argument (plus the conventional extension, ‘<span class="file">.so</span>’, ‘<span class="file">.sl</span>’, ‘<span class="file">.dll</span>’, ...). This is intended to add safety for packages, which can ensure by using this argument that no other package can override their external symbols. This is used in the same way as in <code><a href="Foreign.html">.C</a></code>, <code><a href="CallExternal.html">.Call</a></code>, <code><a href="Foreign.html">.Fortran</a></code> and <code><a href="CallExternal.html">.External</a></code> functions.</p> </td></tr> <tr valign="top"><td><code>type</code></td> <td> <p>The type of symbol to look for: can be any (<code>""</code>, the default), <code>"Fortran"</code>, <code>"Call"</code> or <code>"External"</code>.</p> </td></tr> </table> <h3>Details</h3> <p>The objects <code>dyn.load</code> loads are called ‘dynamically loadable libraries’ (abbreviated to ‘DLL’) on all platforms except macOS, which uses the term for a different sort of object. On Unix-alikes they are also called ‘dynamic shared objects’ (‘DSO’), or ‘shared objects’ for short. (The POSIX standards use ‘executable object file’, but no one else does.) </p> <p>See ‘See Also’ and the ‘Writing R Extensions’ and ‘R Installation and Administration’ manuals for how to create and install a suitable DLL. </p> <p>Unfortunately a very few platforms (e.g., Compaq Tru64) do not handle the <code>PACKAGE</code> argument correctly, and may incorrectly find symbols linked into <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span>. </p> <p>The additional arguments to <code>dyn.load</code> mirror the different aspects of the mode argument to the <code>dlopen()</code> routine on POSIX systems. They are available so that users can exercise greater control over the loading process for an individual library. In general, the default values are appropriate and you should override them only if there is good reason and you understand the implications. </p> <p>The <code>local</code> argument allows one to control whether the symbols in the DLL being attached are visible to other DLLs. While maintaining the symbols in their own namespace is good practice, the ability to share symbols across related ‘chapters’ is useful in many cases. Additionally, on certain platforms and versions of an operating system, certain libraries must have their symbols loaded globally to successfully resolve all symbols. </p> <p>One should be careful of the potential side-effect of using lazy loading via the <code>now</code> argument as <code>FALSE</code>. If a routine is called that has a missing symbol, the process will terminate immediately. The intended use is for library developers to call with value <code>TRUE</code> to check that all symbols are actually resolved and for regular users to call with <code>FALSE</code> so that missing symbols can be ignored and the available ones can be called. </p> <p>The initial motivation for adding these was to avoid such termination in the <code>_init()</code> routines of the Java virtual machine library. However, symbols loaded locally may not be (read probably) available to other DLLs. Those added to the global table are available to all other elements of the application and so can be shared across two different DLLs. </p> <p>Some (very old) systems do not provide (explicit) support for local/global and lazy/eager symbol resolution. This can be the source of subtle bugs. One can arrange to have warning messages emitted when unsupported options are used. This is done by setting either of the options <code>verbose</code> or <code>warn</code> to be non-zero via the <code><a href="options.html">options</a></code> function. </p> <p>There is a short discussion of these additional arguments with some example code available at <a href="http://www.stat.ucdavis.edu/~duncan/R/dynload/">http://www.stat.ucdavis.edu/~duncan/R/dynload/</a>. </p> <h3>Value</h3> <p>The function <code>dyn.load</code> is used for its side effect which links the specified DLL to the executing <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> image. Calls to <code>.C</code>, <code>.Call</code>, <code>.Fortran</code> and <code>.External</code> can then be used to execute compiled C functions or Fortran subroutines contained in the library. The return value of <code>dyn.load</code> is an object of class <code>DLLInfo</code>. See <code><a href="getLoadedDLLs.html">getLoadedDLLs</a></code> for information about this class. </p> <p>The function <code>dyn.unload</code> unlinks the DLL. Note that unloading a DLL and then re-loading a DLL of the same name may or may not work: on Solaris it uses the first version loaded. Note also that some DLLs cannot be safely unloaded at all: unloading a DLL which implements C finalizers but does not unregister them on unload causes R to crash. </p> <p><code>is.loaded</code> checks if the symbol name is loaded <em>and searchable</em> and hence available for use as a character string value for argument <code>.NAME</code> in <code>.C</code> or <code>.Fortran</code> or <code>.Call</code> or <code>.External</code>. It will succeed if any one of the four calling functions would succeed in using the entry point unless <code>type</code> is specified. (See <code><a href="Foreign.html">.Fortran</a></code> for how Fortran symbols are mapped.) Note that symbols in base packages are not searchable, and other packages can be so marked. </p> <h3>Warning</h3> <p>Do not use <code>dyn.unload</code> on a DLL loaded by <code><a href="library.dynam.html">library.dynam</a></code>: use <code><a href="library.dynam.html">library.dynam.unload</a></code>. This is needed for system housekeeping. </p> <h3>Note</h3> <p><code>is.loaded</code> requires the name you would give to <code>.C</code> etc and <strong>not</strong> (as in S) that remapped by the defunct functions <code>symbol.C</code> or <code>symbol.For</code>. </p> <p>By default, the maximum number of DLLs that can be loaded is now 614 when the OS limit on the number of open files allows or can be increased, but less otherwise (but it will be at least 100). A specific maximum can be requested <em>via</em> the environment variable <span class="env">R_MAX_NUM_DLLS</span>, which has to be set (to a value between 100 and 1000 inclusive) before starting an <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> session. If the OS limit on the number of open files does not allow using this maximum and cannot be increased, <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> will fail to start with an error. The maximum is not allowed to be greater than 60% of the OS limit on the number of open files (essentially unlimited on Windows, on Unix typically 1024, but 256 on macOS). The limit can sometimes (including on macOS) be modified using command <code>ulimit -n</code> (<code>sh</code>, <code>bash</code>) or <code>limit descriptors</code> (<code>csh</code>) in the shell used to launch <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span>. Increasing <span class="env">R_MAX_NUM_DLLS</span> comes with some memory overhead. </p> <p>If the OS limit on the number of open files cannot be determined, the DLL limit is 100 and cannot be changed <em>via</em> <span class="env">R_MAX_NUM_DLLS</span>. </p> <p>The creation of DLLs 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 <code>dlopen</code> has become the POSIX standard for doing this. Under Unix-alikes <code>dyn.load</code> uses the <code>dlopen</code> mechanism and should work on all platforms which support it. On Windows it uses the standard mechanism (<code>LoadLibrary</code>) for loading DLLs. </p> <p>The original code for loading DLLs in Unix-alikes was provided by Heiner Schwarte. </p> <h3>References</h3> <p>Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988) <em>The New S Language</em>. Wadsworth & Brooks/Cole. </p> <h3>See Also</h3> <p><code><a href="library.dynam.html">library.dynam</a></code> to be used inside a package's <code><a href="ns-hooks.html">.onLoad</a></code> initialization. </p> <p><code><a href="../../utils/html/SHLIB.html">SHLIB</a></code> for how to create suitable DLLs. </p> <p><code><a href="Foreign.html">.C</a></code>, <code><a href="Foreign.html">.Fortran</a></code>, <code><a href="CallExternal.html">.External</a></code>, <code><a href="CallExternal.html">.Call</a></code>. </p> <h3>Examples</h3> <pre> ## expect all of these to be false in R >= 3.0.0. is.loaded("supsmu") # Fortran entry point in stats is.loaded("supsmu", "stats", "Fortran") is.loaded("PDF", type = "External") # pdf() device in grDevices </pre> <hr /><div style="text-align: center;">[Package <em>base</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>