DLFCN(3) | Library Functions Manual | DLFCN(3) |
dlopen
, dlclose
,
dlsym
, dlvsym
,
dladdr
, dlctl
,
dlerror
—
#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);
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:
One of the following values may be used to specify symbol visibility:
RTLD_GLOBAL
RTLD_LOCAL
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
dlclose
().
The same behaviour may be requested by -z nodelete
option of the static linker
ld(1).RTLD_NOLOAD
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
dlopen
().RTLD_DEFAULT
RTLD_NEXT
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
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
dli_fbase
dli_sname
dli_saddr
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.
dlopen
()s a module that needs
libpthread but isn't linked against it itself.
dl*
functions first appeared in SunOS 4.
June 25, 2011 | NetBSD 9.2 |