dladdr, dlclose, dlerror, dlopen, dlsym, dlvsym - program-
ming interface to dynamic linking loader
#include <dlfcn.h>
The four functions dlopen(), dlsym(), dlclose(), dlerror()
implement the interface to the dynamic linking loader.
The function dlerror() returns a human readable string
describing the most recent error that occurred from any of
the dl routines (dlopen, dlsym or dlclose) since the last
call to dlerror(). It returns NULL if no errors have
occurred since initialization or since it was last called.
The function dlopen() loads the dynamic library file named
by the null-terminated string filename and returns an
opaque "handle" for the dynamic library. If filename is
NULL, then the returned handle is for the main program.
If filename contains a slash ("/"), then it is interpreted
as a (relative or absolute) pathname. Otherwise, the
dynamic linker searches for the library as follows (see
ld.so(8) for further details):
program contains a DT_RPATH tag, and does not con-
tain a DT_RUNPATH tag, then the directories listed
in the DT_RPATH tag are searched.
defined to contain a colon-separated list of direc-
tories, then these are searched. (As a security
measure this variable is ignored for set-UID and
set-GID programs.)
program contains a DT_RUNPATH tag, then the direc-
tories listed in that tag are searched.
ldconfig(8)) is checked to see whether it contains
an entry for filename.
that order).
then these are also automatically loaded by the dynamic
linker using the same rules. (This process may occur
recursively, if those libraries in turn have dependencies,
and so on.)
When RTLD_NOW is specified, or the environment variable
LD_BIND_NOW is set to a non-empty string, all undefined
symbols in the library are resolved before dlopen()
returns. If this cannot be done, an error is returned.
Otherwise binding is lazy: symbol values are first
resolved when needed.
case the external symbols defined in the library will be
made available for symbol resolution of subsequently
loaded libraries. (The converse of RTLD_GLOBAL is
RTLD_LOCAL. This is the default.)
for the main program. When given to dlsym(), this handle
causes a search for a symbol in the main program, followed
by all shared libraries loaded at program startup, and
then all shared libraries loaded by dlopen() with the flag
RTLD_GLOBAL.
libraries in that library's dependency list and any other
libraries previously opened with the RTLD_GLOBAL flag. If
the executable was linked with the flag "-rdynamic" (or,
synonymously, "--export-dynamic"), then the global symbols
in the executable will also be used to resolve references
in a dynamically loaded library.
same file handle is returned. The dl library maintains
reference counts for library handles, so a dynamic library
is not deallocated until dlclose() has been called on it
as many times as dlopen() has succeeded on it. The _init
routine, if present, is only called once. But a subsequent
call with RTLD_NOW may force symbol resolution for a
library earlier loaded with RTLD_LAZY.
The function dlsym() takes a "handle" of a dynamic library
returned by dlopen and the NUL-terminated symbol name,
returning the address where that symbol is loaded into
memory. If the symbol is not found, in the specified
library or any of the libraries that were automatically
loaded by dlopen() when that library was loaded, dlsym()
returns NULL. (The search performed by dlsym() is breadth
first through the dependency tree of these libraries.)
Since the value of the symbol could actually be NULL (so
that a NULL return from dlsym() need not indicate an
error), the correct way to test for an error is to call
dlerror() to clear any old error conditions, then call
dlsym(), and then call dlerror() again, saving its return
value into a variable, and check whether this saved value
is not NULL.
RTLD_NEXT. The former will find the first occurrence of
the desired symbol using the default library search order.
The latter will find the next occurrence of a function in
the search order after the current library. This allows
one to provide a wrapper around a function in another
shared library.
The function dlclose() decrements the reference count on
the dynamic library handle handle. If the reference count
drops to zero and no other loaded libraries use symbols in
it, then the dynamic library is unloaded.
on error.
The linker recognizes special symbols _init and _fini. If
a dynamic library exports a routine named _init, then that
code is executed after the loading, before dlopen()
returns. If the dynamic library exports a routine named
_fini, then that routine is called just before the library
is unloaded. In case you need to avoid linking against
the system startup files, this can be done by giving gcc
the "-nostartfiles" parameter on the command line.
dlib options, is not recommended. Their use may result in
undesired behavior, since the constructor/destructor rou-
tines will not be executed (unless special measures are
taken).
__attribute__((constructor)) and __attribute__((destruc-
tor)) function attributes. See the gcc info pages for
information on these. Constructor routines are executed
before dlopen returns, and destructor routines are exe-
cuted before dlclose returns.
Glibc adds two functions not described by POSIX, with pro-
totypes
#include <dlfcn.h>
to resolve name and file where it is located. Information
is stored in the Dl_info structure:
const char *dli_fname;/* File name of defining object */
void *dli_fbase; /* Load address of that object */
const char *dli_sname;/* Name of nearest lower symbol */
void *dli_saddr; /* Exact value of nearest symbol */
} Dl_info;
version string as additional argument.
EXAMPLE
Load the math library, and print the cosine of 2.0:
#include <stdio.h>
#include <dlfcn.h>
void *handle;
double (*cosine)(double);
char *error;
if (!handle) {
fprintf (stderr, "%s\n", dlerror());
exit(1);
}
*(void **) (&cosine) = dlsym(handle, "cos");
if ((error = dlerror()) != NULL) {
fprintf (stderr, "%s\n", error);
exit(1);
}
dlclose(handle);
return 0;
}
build the program with the following command:
compiled as follows, using bar.c as the example name:
The symbols RTLD_DEFAULT and RTLD_NEXT are defined by
<dlfcn.h> only when _GNU_SOURCE was defined before includ-
ing it.
The dlopen interface standard comes from SunOS. That sys-
tem also has dladdr, but not dlvsym.
POSIX 1003.1-2003 describes dlclose, dlerror, dlopen,
dlsym.
ld(1), ldd(1), ld.so(8), ldconfig(8), ld.so info pages,
gcc info pages, ld info pages