NAME
dlopen,
dlclose,
dlsym,
dlvsym,
dladdr,
dlctl,
dlerror —
dynamic link
interface
LIBRARY
(These functions are not in a library. They are included in every dynamically
linked program automatically.)
SYNOPSIS
#include <dlfcn.h>
void *
dlopen(
const char
*path,
int mode);
int
dlclose(
void
*handle);
void *
dlsym(
void *
restrict handle,
const char
* restrict symbol);
void *
dlvsym(
void *
restrict handle,
const char
* restrict symbol,
const
char *version);
int
dladdr(
void *
restrict addr,
Dl_info *
restrict dli);
int
dlctl(
void
*handle,
int cmd,
void *data);
char *
dlerror(
void);
DESCRIPTION
These functions provide an interface to the run-time linker
ld.so(1). They allow new shared
objects to be loaded into the process' address space under program control.
The
dlopen() function takes the name of a shared object as the
first argument. The
path argument can be specified as
either an absolute pathname to a shared object or just the name of the shared
object itself. When an absolute pathname is specified, only the path provided
will be searched. When just a shared object name is specified, the same search
rules apply that are used for “intrinsic” shared object searches.
(see
ld.elf_so(1))
Shared libraries take the following form:
“lib⟨name⟩.so[
.xx[.yy]]”.
The shared object is mapped into the address space, relocated, and its external
references are resolved in the same way as is done with the implicitly loaded
shared libraries at program startup.
If the first argument is
NULL
,
dlopen() returns a
handle on the
global symbol object. This object provides access to all symbols from an
ordered set of objects consisting of the original program image and any
dependencies loaded during startup.
The
mode parameter specifies symbol resolution time and
symbol visibility. One of the following values may be used to specify symbol
resolution time:
-
-
RTLD_NOW
- Symbols are resolved immediately.
-
-
RTLD_LAZY
- Symbols are resolved when they are first referred to. This
is the default value if resolution time is unspecified.
One of the following values may be used to specify symbol visibility:
-
-
RTLD_GLOBAL
- The object's symbols and the symbols of its dependencies
will be visible to other objects.
-
-
RTLD_LOCAL
- The object's symbols and the symbols of its dependencies
will not be visible to other objects. This is the default value if
visibility is unspecified.
To specify both resolution time and visibility, bitwise inclusive OR one of each
of the above values together. If an object was opened with
RTLD_LOCAL
and later opened with
RTLD_GLOBAL
, then it is promoted to
RTLD_GLOBAL
.
Additionally, one of the following flags may be ORed into the
mode argument:
-
-
RTLD_NODELETE
- Prevents unload of the loaded object on
dlclose(). The same behaviour may be requested by
-z nodelete option of the static linker
ld(1).
-
-
RTLD_NOLOAD
- Only return valid handle for the object if it is already
loaded in the process address space, otherwise do not load the object and
return
NULL
.
dlopen() returns a
handle to be used in
calls to
dlclose(),
dlsym(),
dlvsym(), and
dlctl(). If the named shared
object has already been loaded by a previous call to
dlopen() (and not yet unloaded by
dlclose()), a
handle referring to the
resident copy is returned.
dlclose() unlinks and removes the object referred to by
handle from the process address space. If multiple calls
to
dlopen() have been done on this object, or the object was
one loaded at startup time, or the object is a dependency of another object
then the object is removed when its reference count drops to zero.
dlclose() returns 0 on success and non-zero on failure.
dlsym() looks for a definition of
symbol
in the shared object designated by
handle, and all
shared objects that are listed as dependencies. The symbol's address is
returned. If the symbol cannot be resolved,
NULL
is
returned.
dlsym() may also be called with special
handle values.
dlsym() respects symbol
visibility as specified by the
dlopen()
mode parameter. However, the symbols of an object's
dependencies are always visible to it. All shared objects loaded at program
startup are globally visible. Only the symbols in the main executable that are
referenced by a shared object at link time will be visible unless it has been
linked with the --export-dynamic option where all of its symbols will be
visible. The following special
handle values may be used
with
dlsym():
-
-
NULL
- Interpreted as a reference to the executable or shared
object from which the call is being made. Thus an object can reference its
own symbols and the symbols of its dependencies without calling
dlopen().
-
-
RTLD_DEFAULT
- All the visible shared objects and the executable will be
searched in the order they were loaded.
-
-
RTLD_NEXT
- The search for symbol is limited to
the visible shared objects which were loaded after the one issuing the
call to dlsym(). Thus, if dlsym() is
called from the main program, all the visible shared libraries are
searched. If it is called from a shared library, all subsequently visible
shared libraries are searched.
-
-
RTLD_SELF
- The search for symbol is limited to
the shared object issuing the call to dlsym() and those
shared objects which were loaded after it that are visible.
dlvsym() does the same as
dlsym() but takes
a
version string as an additional argument. Both the
symbol and the
version must match
in order for the symbol to be resolved.
dladdr() examines all currently mapped shared objects for a
symbol whose address -- as mapped in the process address space -- is closest
to but not exceeding the value passed in the first argument
addr. The symbols of a shared object are only eligible
if
addr is between the base address of the shared object
and the value of the symbol “_end” in the same shared object. If
no object for which this condition holds true can be found,
dladdr() will return 0. Otherwise, a non-zero value is
returned and the
dli argument will be used to provide
information on the selected symbol and the shared object it is contained in.
The
dli argument points at a caller-provided
Dl_info structure defined as follows:
typedef struct {
const char *dli_fname; /* File defining the symbol */
void *dli_fbase; /* Base address */
const char *dli_sname; /* Symbol name */
const void *dli_saddr; /* Symbol address */
} Dl_info;
The structure members are further described as follows:
-
-
dli_fname
- The pathname of the shared object containing the address
addr.
-
-
dli_fbase
- The base address at which this shared object is loaded in
the process address space. This may be zero if the symbol was found in the
internally generated “copy” section (see
link(5)) which is not
associated with a file.
-
-
dli_sname
- points at the nul-terminated name of the selected
symbol
-
-
dli_saddr
- is the actual address (as it appears in the process address
space) of the symbol.
Note: both strings pointed at by
dli_fname and
dli_sname reside in memory private to the run-time
linker module and should not be modified by the caller.
In dynamically linked programs, the address of a global function will point to
its program linkage table entry, rather than to the entry point of the
function itself. This causes most global functions to appear to be defined
within the main executable, rather than in the shared libraries where the
actual code resides.
dlctl() provides an interface similar to
ioctl(2) to control several
aspects of the run-time linker's operation. This interface is currently under
development.
dlerror() returns a character string representing the most
recent error that has occurred while processing one of the other functions
described here. If no dynamic linking errors have occurred since the last
invocation of
dlerror(),
dlerror() returns
NULL
. Thus, invoking
dlerror() a
second time, immediately following a prior invocation, will result in
NULL
being returned.
ERRORS
The error “Cannot dlopen non-loadable /usr/lib/libpthread.so.1” is
generated when a program
dlopen()
s a
module that needs libpthread but isn't linked against it itself.
SEE ALSO
ld(1),
rtld(1),
link(5)
HISTORY
Some of the
dl* functions first appeared in SunOS 4.