dlopen, dlclose, dlsym, dladdr, dlctl, dlerror - dynamic
link interface
#include <dlfcn.h>
void *
dlopen(const char *path, int mode);
int
dlclose(void *handle);
void *
dlsym(void *handle, const char *symbol);
int
dladdr(const void *addr, Dl_info *info);
int
dlctl(void *handle, int cmd, void *data);
const char *
dlerror(void);
These functions provide an interface to the run-time linker
ld.so(1).
They allow new shared objects to be loaded into a process's
address space
under program control.
The dlopen() function takes a name of a shared object as its
first argument.
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.
The path argument can either be an absolute pathname or it
can be of the
form ``lib<name>.so[.xx[.yy]]'' in which case the same library search
rules apply that are used for ``intrinsic'' shared library
searches. A
null pointer supplied for path is interpreted as a reference
to the main
executable of the process. The second argument currently
has no effect,
but should be set to DL_LAZY for future compatibility.
dlopen() returns a handle to be used in calls to dlclose(),
dlsym(), 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 once loaded at startup time)
the object is
removed when its reference count drops to zero.
dlsym() looks for a definition of symbol in the shared object designated
by handle. The symbol's address is returned. If the symbol
cannot be
resolved, NULL is returned.
If dlsym() is called with the special handle NULL, it is interpreted as a
reference to the executable or shared object from which the
call is being
made. Thus a shared object can reference its own symbols.
If dlsym() is called with the special handle RTLD_DEFAULT,
all the shared
objects will be searched in the order they were loaded.
If dlsym() is called with the special handle RTLD_NEXT, then
the search
for the symbol is limited to the shared objects which were
loaded after
the one issuing the call to dlsym(). Thus, if the function
is called
from the main program, all the shared libraries are
searched. If it is
called from a shared library, all subsequent shared libraries are
searched.
If dlsym() is called with the special handle RTLD_SELF, then
the search
for the symbol is limited to the shared object issuing the
call to
dlsym() and those shared objects which were loaded after it.
dladdr() queries the dynamic linker for information about
the shared object
containing the address addr. The information is returned in the
structure specified by info. The structure contains at
least the following
members:
const char *dli_fname The pathname of the shared object
containing
the address addr.
void *dli_fbase The base address at which the
shared object is
mapped into the address space of
the calling
process.
const char *dli_sname The name of the nearest run-time
symbol with a
address less than or equal to
addr.
If no symbol with a suitable address is found,
both this field and dli_saddr are
set to NULL.
void *dli_saddr The address of the symbol returned
in
dli_sname.
If a mapped shared object containing addr cannot be found,
dladdr() returns
0. In that case, a message detailing the failure can
be retrieved
by calling dlerror(). On success, a non-zero value is returned. 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.
ld(1), ld.so(1), link(5)
Some of the dl* functions first appeared in SunOS 4.
An error that occurs while processing a dlopen() request results in the
termination of the program.
OpenBSD 3.6 September 30, 1995
[ Back ] |
