 |
Index for
Section 3 |
|
 |
Alphabetical
listing for D |
|
 |
Bottom of
page |
|
dlopen(3)
NAME
dlopen - gain access to an executable object file
SYNOPSIS
#include <dlfcn.h>
void *dlopen(
const char *file,
int mode );
PARAMETERS
file
Used to construct a pathname to an object file.
mode
Determines 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.
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 specified below (see
loader(5) for more details on shared library search directories):
1. The current directory
2. The program's rpath directories
3. LD_LIBRARY_PATH directories
4. 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 references 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:
RTLD_LAZY
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.
RTLD_NOW
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:
RTLD_GLOBAL
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.
RTLD_LOCAL
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 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 resolution 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
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
relocating 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.
SEE ALSO
dlclose(3), dlerror(3), dlsym(3), ld(1), loader(5)
|
Index for
Section 3 |
|
|
Alphabetical
listing for D |
|
 |
Top of
page |
|