dlopen(3X) dlopen(3X)
NAME
dlopen - open a shared object
SYNOPSIS
cc [flag ...] file ... -ldl [library ...]
#include <dlfcn.h>
void *dlopen(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 pointer (handle) which 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() will make the symbols contained
in the original a.out, and all objects loaded with the RTLDGLOBAL
mode, available through dlsym() (see NOTES, no. 3).
A shared object may specify other objects that it "needs" in order to
execute properly. These needed objects are specified by DTNEEDED
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 loaded 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 reloca-
tions take place and may have the following values:
RTLDLAZY Under this mode, only references to data symbols are relo-
cated 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.
RTLDNOW Under this mode, all necessary relocations are performed
when the object is first loaded. This may result in 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.
Page 1 Reliant UNIX 5.44 Printed 11/98
dlopen(3X) dlopen(3X)
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 RTLDGLOBAL, 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 occurrence 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
RTLDGLOBAL). 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 dependen-
cies for the object currently being dlopen'd.
RESULT
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() will return
NULL. More detailed diagnostic information will be available through
dlerror().
NOTES
1. If other shared objects were link edited with pathname when
pathname was built, those objects will automatically be loaded by
dlopen(). The directory search path that will be used to find both
pathname and the other needed objects is the same as that used by
the runtime loader. In particular, pathname is searched for in
a) the directory specified by pathname if it is not a simple file
name (i.e. it contains a "/" character). In this case, the exact
file is the only placed searched; steps b) through d) below are
ignored.
b) any path specified via the LDRUNPATH environment variable set
when the executable was link edited [see ld(1)].
c) any directory specified by the environment variable
LDLIBRARYPATH resp. LDLIBRARY64sPATH.
Page 2 Reliant UNIX 5.44 Printed 11/98
dlopen(3X) dlopen(3X)
These environment variables should contain a colon-separated
list of directories, in the same format as the PATH variable
[see sh(1)]. 32-bit programs will only examine LDLIBRARYPATH,
LDLIBRARY64sPATH will be ignored. 64-bit programs will examine
LDLIBRARY64sPATH instead, if it is set; LDLIBRARYPATH will
be ignored then. If LDLIBRARY64sPATH is not set, 64-bit pro-
grams will examine the variable LDLIBRARYPATH.
Both variables will be ignored if the process is running
setuid() or setgid() [see exec(2)].
d) the default search paths will be used. These are
/lib:/usr/lib:/usr/lib/cmplrs/cc for 32-bit programs,
/lib64s:/usr/lib64s:/usr/lib64s/cmplrs/cc for 64-bit programs.
2. 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 will only be loaded 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 working directory is /usr/home/me/workdir,
...
void *handle1;
void *handle2;
handle1 = dlopen("../mylibs/mylib.so", RTLDLAZY);
handle2 = dlopen("/usr/home/me/mylibs/mylib.so", RTLDLAZY);
...
will result in mylibs.so being loaded twice for the current pro-
cess. On the other hand, given the same object and current working
directory, if LDLIBRARYPATH=/usr/home/me/mylibs, then
...
void *handle1;
void *handle2;
handle1 = dlopen("mylib.so", RTLDLAZY);
handle2 = dlopen("/usr/home/me/mylibs/mylib.so", RTLDLAZY);
...
will result in mylibs.so being loaded only once.
3. Objects loaded by a single invocation of dlopen() may import sym-
bols from one another or from any object loaded automatically dur-
ing program startup, but objects loaded by one dlopen() invocation
may not directly reference symbols from objects loaded by a dif-
ferent dlopen() invocation (unless loaded using the RTLDGLOBAL
mode). Those symbols may, however, be referenced indirectly using
dlsym().
Page 3 Reliant UNIX 5.44 Printed 11/98
dlopen(3X) dlopen(3X)
Users who wish 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: specifi-
cally those referenced by the shared objects with which the a.out
is linked.
4. The dynamic linker is only available with the libc dynamic library
(do not use -dn).
SEE ALSO
cc(1), ld(1), sh(1), exec(2), dlclose(3X), dlerror(3X), dlsym(3X).
Chapter on "The C compilation system" in "Guide to Tools for Program-
ming in C".
Page 4 Reliant UNIX 5.44 Printed 11/98