| dynload {rdyncall} | R Documentation |
Low-level functions to load and unload shared libraries and to resolve symbols.
.dynload(libname, auto.unload=TRUE) .dynsym(libhandle, symname, protect.lib=TRUE) .dynunload(libhandle)
libname |
A character string specifying the library file in short, relative- or absolute-path form. |
libhandle |
An external pointer representing a handle to an open library. |
symname |
A character string specifying the symbolic name to lookup. |
auto.unload |
A logical indicating if a finalizer should be registered that will automatically unload the library |
protect.lib |
A logical indicating if the external pointer representing the symbol will protect the lib object |
The function .dynload searches for a library specified by libname.
It loads the library to the run-time process and returns its libhandle (library handle)
as an external pointer.
Function pointers can be resolved using .dynsym to lookup a symbol given by symname
in a library specified by libhandle.
.dynunload can be used to unload a library from the run-time process.
.dynload returns an external pointer libhandle on success. Otherwise NULL is returned, if the library is not found or the linkage failed.
.dynfind returns an external pointer address on sucess. Otherwise NULL is returned, if the address was invalid or the symbol has not been found.
.dynunload always returns NULL.
Shared libraries are single files that contain compiled code, data and meta-information. The code and data can be loaded and mapped to a process at run-time once. Operating system platforms have slightly different schemes for naming, searching and linking options.
| Platform | Binary format | File Extension |
| Linux, BSD derivates and Sun Solaris | ELF format | lib*.so |
| Darwin / Apple Mac OS X | Mach-O format | lib*.dylib |
| Microsoft Windows | PE format | *.DLL |
These search rules will only be applied to path names that do not contain an embedded '/'.
LD_LIBRARY_PATH environment variable is defined to contain a colon-separated list of
directories, then these are searched.
/etc/ld.so.cache is checked to see whether it contains an entry for filename.
/lib and /usr/lib are searched (in that order).
dlopen() searches for a compatible Mach-O file in the directories specified by a set of environment variables and the process's current working directory. When set, the environment variables must contain a colon-separated list of directory paths, which can be absolute or relative to the current working directory. The environment variables are LD_LIBRARY_PATH, DYLD_LIBRARY_PATH, and DYLD_FALLBACK_LIBRARY_PATH. The first two variables have no default value. The default value of DYLD_FALLBACK_LIBRARY_PATH is $HOME/lib;/usr/local/lib;/usr/lib. dlopen() searches the directories specified in the environment variables in the order they are listed.
When path doesn't contain a slash character (i.e. it is just a leaf name), dlopen() searches the fol-lowing following lowing the following until it finds a compatible Mach-O file: $LD_LIBRARY_PATH, $DYLD_LIBRARY_PATH, current working directory, $DYLD_FALLBACK_LIBRARY_PATH.
When path contains a slash (i.e. a full path or a partial path) dlopen() searches the following the following until it finds a compatible Mach-O file: $DYLD_LIBRARY_PATH (with leaf name from path ), cur-rent current rent working directory (for partial paths), $DYLD_FALLBACK_LIBRARY_PATH (with leaf name from path ).
If no file name extension is specified in the lpFileName parameter, the default library extension .dll is appended. However, the file name string can include a trailing point character (.) to indicate that the module name has no extension. When no path is specified, the function searches for loaded modules whose base name matches the base name of the module to be loaded. If the name matches, the load succeeds. Otherwise, the function searches for the file in the following sequence:
Windows Server 2003, Windows XP SP1: The default value of HKLMSystemCurrentControlSetControlSession ManagerSafeDllSearchMode is 1 (current directory is searched after the system and Windows directories).
Windows XP: If HKLMSystemCurrentControlSetControlSession ManagerSafeDllSearchMode is 1, the current directory is searched after the system and Windows directories, but before the directories in the PATH environment variable. The default value is 0 (current directory is searched before the system and Windows directories).
The first directory searched is the one directory containing the image file used to create the calling process. Doing this allows private dynamic-link library (DLL) files associated with a process to be found without adding the process's installed directory to the PATH environment variable.
The search path can be altered using the SetDllDirectory function. This solution is recommended instead of using SetCurrentDirectory or hard-coding the full path to the DLL.
If a path is specified and there is a redirection file for the application, the function searches for the module in the application's directory. If the module exists in the application's directory, the LoadLibrary function ignores the specified path and loads the module from the application's directory. If the module does not exist in the application's directory, LoadLibrary loads the module from the specified directory. For more information, see Dynamic Link Library Redirection.