dlfcn(3)
- NetBSD Manual Pages
DLFCN(3) NetBSD Library Functions Manual DLFCN(3)
NAME
dlopen, dlclose, dlsym, dladdr, dlctl, dlerror -- dynamic link interface
LIBRARY
(These functions are not in a library. They are included in every dynam-
ically 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);
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 a name of a
shared object as the 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 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. 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 second argument has currently no effect, but should be set to
RTLD_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 one 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 symbols address is returned. If the symbol cannot be
resolved, NULL is returned.
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 member dli_sname points at the nul-terminated name of the selected
symbol, and dli_saddr is the actual address (as it appears in the process
address space) of the symbol. The member dli_fname points at the file
name corresponding to the shared object in which the symbol was found,
while dli_fbase is the base address at which this shared object is loaded
in the process address space. dli_fname and dli_fbase may be zero if the
symbol was found in the internally generated ``copy'' section (see
link(5)) which is not associated with a file. 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.
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 invoca-
tion of dlerror(), dlerror() returns NULL. Thus, invoking dlerror() a
second time, immediately following a prior invocation, will result in
NULL being returned.
SEE ALSO
ld(1), rtld(1), link(5)
HISTORY
Some of the dl* functions first appeared in SunOS 4.
BUGS
An error that occurs while processing a dlopen() request results in the
termination of the program.
NetBSD 5.1.5 March 31, 2008 NetBSD 5.1.5
Powered by man-cgi (2024-08-24).
Maintained for NetBSD
by Kimmo Suominen.
Based on man-cgi by Panagiotis Christias.