dlopen(3X) MISCELLANEOUS LIBRARY FUNCTIONS 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. (See ``C
Compilation System'' in the Programmer's Guide: ANSI C and
Programming Support Tools). These routines are available in
a library which is loaded if the option -ldl is used with cc
or ld.
dlopen makes a shared object available to a running process.
dlopen returns to the process a 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. path-
name 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 of the objects that
were loaded at program startup with the a.out, available
through dlsym.
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:
RTLDLAZY
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.
RTLDNOW
Under this mode, all necessary relocations are per-
formed when the object is first loaded. This may
result in some wasted effort, if relocations are per-
formed 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.
Last change: C Programming Language Utilities 1
dlopen(3X) MISCELLANEOUS LIBRARY FUNCTIONS dlopen(3X)
SEE ALSO
cc(1), ld(1), sh(1), exec(2), dlclose(3X), dlerror(3X),
dlsym(3X).
The ``C Compilation System'' chapter in the Programmer's
Guide: ANSI C and Programming Support Tools.
DIAGNOSTICS
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 diagnos-
tic information will be available through dlerror.
NOTES
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 may
be specified by setting the environment variable
LDLIBRARYPATH. This environment variable should contain a
colon-separated list of directories, in the same format as
the PATH variable [see sh(1)]. LDLIBRARYPATH will be
ignored if the process is running setuid or setgid [see
exec(2)] or if the name specified is not a simple file name
(i.e. 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
will only be loaded once into the address space of the
current process. The same object referenced by two dif-
ferent 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
process. On the other hand, given the same object and
current working directory, if
LDLIBRARYPATH=/usr/home/me/mylibs, then
Last change: C Programming Language Utilities 2
dlopen(3X) MISCELLANEOUS LIBRARY FUNCTIONS dlopen(3X)
...
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.
Objects loaded by a single invocation of dlopen may import
symbols from one another or from any object loaded automati-
cally during program startup, but objects loaded by one dlo-
pen invocation may not directly reference symbols from
objects loaded by a different dlopen invocation. Those sym-
bols may, however, be referenced indirectly using dlsym.
Users who wish to gain access to the symbol table of the
a.out itself using dlsym(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 sym-
bols defined in the a.out: specifically those referenced by
the shared objects with which the a.out is linked.
Last change: C Programming Language Utilities 3