dlopen(3) Library Functions Manual dlopen(3)
NAME
dlopen - Gain access to an executable object file
SYNOPSIS
#include <dlfcn.h>
void *dlopen(const char *file, int mode)
PARAMETERS
Used to construct a pathname to an object file. Determines how dlopen() will operate upon the specified file with respect to the process-
ing of relocations and the scope of visibility of the symbols provided within the file.
DESCRIPTION
The dlopen function provides an interface to the dynamic library loader to allow shared libraries to be loaded and called at run time. The
dlopen function attempts to load the specified file in the address space of the process, resolving symbols as appropriate. Any libraries
that the specified file depends upon are also loaded.
A successful dlopen() returns a handle that the caller can use on subsequent calls to dlsym() and dlclose(). The value of this handle
should not be interpreted in any way by the caller.
The file argument is used to construct a pathname to the object file. If it includes a slash character (/), the file argument is used as
the pathname for the file. Otherwise, dlopen will attempt to locate the file using shared library search directories in the order speci-
fied below (see loader(5) for more details on shared library search directories): The current directory The program's rpath directories
LD_LIBRARY_PATH directories Default shared library directories
If the value of file is 0, dlopen provides a handle on a global symbol object. This object provides access to the symbols from an ordered
set of objects consisting of the original program image file, together with any objects loaded at program startup as specified by that
process image file (for example, shared libraries), and the set of objects loaded using a dlopen operation together with the RTLD_GLOBAL
flag. As the latter set of objects can change during execution, the set identified by the handle can also change dynamically.
Only a single copy of an object file is brought into the address space - even if dlopen() is invoked multiple times in reference to the
file or if different pathnames are used to reference the file.
The mode parameter describes how dlopen() will operate upon the specified file with respect to the processing of relocations and the scope
of visibility of the symbols provided within the file. When an object is brought into the address space of a process, it may contain ref-
erences to symbols whose addresses are not known until the object is loaded. These references must be relocated before the symbols can be
accessed. The mode parameter governs when these relocations take place and may have the following values: The run-time loader performs
relocations only as needed. Typically, this means that the first call to a function in the newly loaded library will cause the resolution
of the address of that function to occur. All necessary relocations are performed when the object is first loaded. This may waste some
processing if relocations are performed for functions that are never referenced. This behaviour may be useful for applications that need to
know, as soon as an object is loaded, that all symbols referenced during execution will be available.
Any object loaded by dlopen() that requires relocations against global symbols can reference: The symbols in the original process image
file Any objects loaded at program startup, from the object itself as well as any other object included in the same dlopen() invocation Any
objects that were loaded in any dlopen() invocation and which specified the RTLD_GLOBAL flag.
To determine the scope of visibility for the symbols loaded with a dlopen() invocation, the mode parameter should be bitwise ORed with one
of the following values: The object's symbols are made available for the relocation processing of any other object. In addition, symbol
lookup using dlopen(0, mode) and an associated dlsym() allows objects loaded with this mode to be searched. The object's symbols are not
made available for the relocation processing of any other object.
If neither RTLD_GLOBAL nor RTLD_LOCAL are specified, RTLD_GLOBAL will be assumed. However, unlike explicit use of RTLD_GLOBAL, this default
mode will allow dynamic rebinding of symbol addresses and recalculation of dynamic relocations as shared libraries are loaded or unloaded.
If a file is specified in multiple dlopen() invocations, mode is interpreted at each invocation. Note, however, that once RTLD_NOW has been
specified, all relocations will have been completed (which renders further RTLD_NOW operations redundant and any further RTLD_LAZY opera-
tions irrelevant). Also note that once RTLD_GLOBAL has been specified, the object will maintain the RTLD_GLOBAL status regardless of any
previous or future specification of RTLD_LOCAL, so long as the object remains in the address space (see dlclose(3)).
Symbols introduced into a program by calls to dlopen() may be used in relocation activities. Symbols so introduced may duplicate symbols
already defined by the program or previous dlopen() operations. To resolve the ambiguities such a situation might present, the resolution
of a symbol reference to symbol definition is based on a symbol resolution order. Two such resolution orders are defined, load or depen-
dency ordering: Load order establishes an ordering among symbol definitions, such that the definition first loaded (including definitions
from the image file and any dependent objects loaded with it) has priority over objects added later (by dlopen()). Load ordering is used in
relocation processing. Dependency ordering uses a breadth-first order starting with a given object, then all of its dependencies, then any
dependents of those, iterating until all dependencies are satisfied.
With the exception of the global symbol object obtained by a dlopen() operation on a file of 0, dependency ordering is used by the dlsym()
function. Load ordering is used in dlsym() operations upon the global symbol object.
When an object is first made accessible by dlopen(), it and its dependent objects are added in dependency order. Once all the objects are
added, relocations are performed using load ordering. Note that if an object or its dependencies had been previously loaded, the load and
dependency orders may yield different resolutions.
RETURN VALUE
The dlopen function will return NULL under the following conditions: If the specified file cannot be found, cannot be opened for reading,
or is not of an appropriate object format for processing by dlopen() If an error occurs during the process of loading the file or relocat-
ing its symbolic references
More detailed diagnostic information will be available through dlerror().
ERRORS
No errors are defined.
NOTES
The dlopen and dlclose routines might dynamically change the resolution of certain symbols referenced by a program or its shared library
dependencies. The dlopen routine might resolve symbols that were previously unresolved, and dlclose might cause resolved symbols to become
unresolved or to be reresolved to a different symbol definition.
Dynamic symbol resolution functions reliably for programs compiled with the -O0 flag. Also, routines that do not call dlopen or dlclose,
either directly or indirectly, can safely depend on dynamic symbol resolution.
The maximum number of shared libraries that can be loaded simultaneously by a single process is approximately 60. This limit can be raised
by reconfiguring the kernel's vm-mapentries parameter. This parameter should be set to at least three times the desired maximum number of
shared libraries that can be loaded by a process. See the manual System Administration for instructions on reconfiguring the vm-mapentries
parameter.
RELATED INFORMATION
dlclose(3), dlerror(3), dlsym(3), ld(1), loader(5). delim off
dlopen(3)