dlopen(3C) dlopen(3C)
NAME
dlopen - open a shared object
SYNOPSIS
#include <dlfcn.h>
void *dlopen(const char *pathname, int mode);
DESCRIPTION
dlopen is one of a family of routines that give the user
direct access to the dynamic linking facilities. dlopen makes
a shared object available to a running process. dlopen
returns to the process a handle the process may use on
subsequent calls to dlsym and dlclose. This value should not
be interpreted in any way by the process. pathname is the
path name of the object to be opened; it may be an absolute
path or relative to the current directory. If the value of
pathname is 0, dlopen makes the symbols contained in the
original a.out, all of the objects that were loaded at program
startup with the a.out, and all objects loaded with the
RTLD_GLOBAL mode, available through dlsym.
A shared object may specify other objects that it ``needs'' in
order to execute properly. These needed objects are specified
by DT_NEEDED entries in the .dynamic section of the original
object. Each needed object may, in turn, specify other needed
objects. All such objects are loaded along with the original
object as a result of the call to dlopen.
When a shared 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
Under this mode, only references to data symbols are
relocated when the object is loaded. References to
functions are not relocated until a given function is
invoked for the first time. This mode should result in
better performance, since a process may not reference
all of the functions in any given shared object.
RTLD_NOW
Under this mode, all necessary relocations are performed
when the object is first loaded. This may result in
Copyright 1994 Novell, Inc. Page 1
dlopen(3C) dlopen(3C)
some wasted effort, if relocations are performed for
functions that are never referenced, but is useful for
applications that need to know as soon as an object is
loaded that all symbols referenced during execution will
be available.
Normally, a dlopen'd object's exported symbols are directly
available only to those other objects that were loaded as a
result of the same call to dlopen. If the mode argument is
logically or'd with the value RTLD_GLOBAL, however, the
exported symbols of all objects loaded via this call to dlopen
are directly available to all other dlopen'd objects.
When searching for symbols to resolve a reference in one of
the objects it is loading, the dynamic linker looks in the
symbol tables of the objects it has already loaded. It uses
the first occurence of the symbol that it finds. The first
object searched is the a.out. Then come the a.out's list of
needed objects, in the order specified in the a.out's .dynamic
section. Then come the second level list of needed entries,
and so on. After all entries loaded on startup have been
searched, the dynamic linker searches all objects loaded as
the result of a call to dlopen (following the rules mentioned
above for RTLD_GLOBAL). For each group, the object actually
specified to dlopen is searched first, then that object's
needed list, in order, then the second level needed entries,
and so on. Since an object is loaded only once and may appear
in the needed list of any number of objects, an object loaded
with one call to dlopen or loaded on startup may be searched
before the objects loaded for the current invocation of
dlopen, even if it appears on the chain of dependencies for
the object currently being dlopen'd.
Return Values
If pathname cannot be found, cannot be opened for reading, is
not a shared object, or if an error occurs during the process
of loading pathname or relocating its symbolic references,
dlopen returns NULL. More detailed diagnostic information is
available through dlerror.
REFERENCES
cc(1), dlclose(3C), dlerror(3C), dlsym(3C), exec(2), ld(1),
sh(1)
Copyright 1994 Novell, Inc. Page 2
dlopen(3C) dlopen(3C)
NOTICES
If other shared objects were link edited with pathname when
pathname was built, those objects are automatically loaded by
dlopen. The directory search path to be used to find both
pathname and the other needed objects may be specified by
setting the environment variable LD_LIBRARY_PATH. This
environment variable should contain a colon-separated list of
directories, in the same format as the PATH variable [see
sh(1)]. LD_LIBRARY_PATH is ignored if the process' real user
id is different from its effective user id or its real group
id is different from its effective group id [see exec(2)] or
if the name specified is not a simple file name (that is,
contains a / character). Objects whose names resolve to the
same absolute or relative path name may be opened any number
of times using dlopen, however, the object referenced is
loaded only once into the address space of the current
process. The same object referenced by two different path
names, however, may be loaded multiple times. For example,
given the object /usr/home/me/mylibs/mylib.so, and assuming
the current directory is /usr/home/me/workdir,
. . .
void *handle1;
void *handle2;
handle1 = dlopen("../mylibs/mylib.so", RTLD_LAZY);
handle2 = dlopen("/usr/home/me/mylibs/mylib.so", RTLD_LAZY);
. . .
results in mylibs.so being loaded twice for the current
process. On the other hand, given the same object and current
directory, if LD_LIBRARY_PATH=/usr/home/me/mylibs, then
. . .
void *handle1;
void *handle2;
handle1 = dlopen("mylib.so", RTLD_LAZY);
handle2 = dlopen("/usr/home/me/mylibs/mylib.so", RTLD_LAZY);
. . .
results in mylibs.so being loaded only once.
Objects loaded by a single invocation of dlopen may import
symbols from one another or from any object loaded
automatically during program startup, but objects loaded by
one dlopen invocation may not directly reference symbols from
objects loaded by a different dlopen invocation (unless loaded
Copyright 1994 Novell, Inc. Page 3
dlopen(3C) dlopen(3C)
using the RTLD_GLOBAL mode). Those symbols, however, may be
referenced indirectly using dlsym.
Users who want to gain access to the symbol table of the a.out
itself using dlopen(0, mode) should be aware that some symbols
defined in the a.out may not be available to the dynamic
linker. The symbol table created by ld for use by the dynamic
linker might contain only a subset of the symbols defined in
the a.out: specifically those referenced by the shared objects
with which the a.out is linked. Other symbols can be
explicitly exported from the a.out through the use of the
-Bexport option to ld(1).
Copyright 1994 Novell, Inc. Page 4