DLFCN(3) BSD Library Functions Manual DLFCN(3)
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 resolu-
tion 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. How-
ever, 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.
BSD
June 25, 2011 BSD