dlopen(3X) (C Programming Language Utilities) 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 "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(1) or ld(1).
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(3X) and dlclose(3X). 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 of the
objects that were loaded at program startup with the a.out, available
through dlsym(3X).
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 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.
7/91 Page 1
dlopen(3X) (C Programming Language Utilities) dlopen(3X)
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 diagnostic information will be available through
dlerror(3X).
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 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 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 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", RTLD_LAZY);
handle2 = dlopen("/usr/home/me/mylibs/mylib.so", RTLD_LAZY);
...
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 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);
...
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 automatically during
program startup, but objects loaded by one dlopen invocation may not
directly reference symbols from objects loaded by a different dlopen
Page 2 7/91
dlopen(3X) (C Programming Language Utilities) dlopen(3X)
invocation. Those symbols may, however, be referenced indirectly
using dlsym(3X).
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(1) 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.
SEE ALSO
cc(1), ld(1), sh(1), exec(2), dlclose(3X), dlerror(3X), dlsym(3X),
and "Compilation System" in the Programmer's Guide: ANSI C and
Programming Support Tools.
7/91 Page 3