dlopen(3)dlopen(3)NAMEdlopen - 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 pro‐
cessing of relocations and the scope of visibility of the symbols pro‐
vided 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 sub‐
sequent 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 specified
below (see loader(5) for more details on shared library search directo‐
ries):
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 iden‐
tified 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 speci‐
fied 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 refer‐
ences 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 per‐
formed 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 reloca‐
tion 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 inter‐
preted at each invocation. Note, however, that once RTLD_NOW has been
specified, all relocations will have been completed (which renders fur‐
ther RTLD_NOW operations redundant and any further RTLD_LAZY operations
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 resolu‐
tion order. Two such resolution orders are defined, load or dependency
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 process‐
ing. 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 depen‐
dent 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 relocating its
symbolic references
More detailed diagnostic information will be available through dler‐
ror().
ERRORS
No errors are defined.
NOTES
The dlopen() and dlclose() routines might dynamically change the reso‐
lution of certain symbols referenced by a program or its shared library
dependencies. The dlopen() routine might resolve symbols that were pre‐
viously 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 res‐
olution.
The maximum number of shared libraries that can be loaded simultane‐
ously 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.
SEE ALSOdlclose(3), dlerror(3), dlsym(3), ld(1), loader(5)dlopen(3)