dlopen - gain access to an executable object file
#include <dlfcn.h>
void *dlopen(
const char *file,
int mode );
Used to construct a pathname to an object file. 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.
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):
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 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:
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 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.
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().
No errors are defined.
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 vmmapentries
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.
dlclose(3), dlerror(3), dlsym(3), ld(1), loader(5)
dlopen(3)
[ Back ] |
