DLOPEN(3) BSD Programmer's Manual DLOPEN(3)NAME
dladdr, dlclose, dlerror, dlopen, dlsym - library routines for dynamic
linking of object files
SYNOPSIS
cc ... -ldl ...
#include <dlfcn.h>
typedef struct {
const char *dli_fname;
void *dli_fbase;
const char *dli_sname;
void *dli_saddr;
} Dl_info;
int
dladdr(void *address, Dl_info *dlip);
int
dlclose(void *handle);
char *
dlerror(void);
void *
dlopen(const char *path, int mode);
void *
dlsym(void *handle, const char *name);
DESCRIPTION
These functions implement the System V dynamic linking routines.
The dlopen() function opens a shared object file and loads it into memo-
ry. The mode argument may be RTLD_NOW, which asks dlopen() to perform
all linking and relocation upon loading the file, or RTLD_LAZY, which
asks dlopen() to delay as much linking and relocation as it can until the
object is referenced. If the environment variable LD_LIBRARY_PATH is
present, dlopen() treats it as a search path for object file names that
do not contain a `/' character. The LD_LIBRARY_PATH variable is ignored
if the process is running setuid. If dlopen() is called multiple times
with the same pathname (absolute pathnames generated by parsing
LD_LIBRARY_PATH are treated identically to a full absolute pathname), it
returns the same handle, and the same relocated copy of the object will
be referenced. If path is NULL, dlopen() returns a handle for the cur-
rently executing program. The dlopen() function returns NULL if it can-
not load the requested object file; otherwise it returns a handle corre-
sponding to the loaded object file, suitable for use with dlsym() and
dlclose().
The dlsym() function looks up the symbol name in the object referenced by
handle and returns the associated address in memory. If dlsym() detects
an error, it returns NULL.
The dlclose() function removes a reference to the given handle. If there
are no more references, dlclose() frees all resources associated with
handle. The dlclose() function returns 0 if it is successful and nonzero
if it detected errors.
The dlerror() function returns an error string associated with the last
error that was reported by dlopen(), dlsym() or dlclose(). The dlerror()
function returns NULL if no errors have been recorded since the previous
call to dlerror().
The dladdr() function is the inverse of the dlsym() function. If the
given address is successfully located inside a module, dladdr() returns
nonzero, otherwise 0. On a successful return, the fields of dlip are
filled in as follows:
dli_fname the pathname of the module
dli_fbase the base address of the module
dli_sname the name of the highest addressed symbol whose address pre-
cedes the given address
dli_faddr the address of that symbol
Shared objects must be linked using the -shared option to the linker
ld(1). The linker flag -rpath may be used to add a directory to the de-
fault search path for shared objects and shared libraries. The linker
flag -E or the C compiler flag -rdynamic should be used to cause the ap-
plication to export its symbols to the shared objects. See the examples
below for details.
ENVIRONMENT
LD_LIBRARY_PATH directory search-path for object files
EXAMPLES
To combine several relocatable object files into a single shared object
file and link them against the shared math library:
ld -shared -o combined.so foo.o bar.o baz.o -lm -lc
To load a shared object file and refer to its data and code, you might
code a program like this:
#include <dlfcn.h>
...
void *handle;
int *datap;
int (*codep)();
char *file = "combined.so";
...
if ((handle = dlopen(file, RTLD_LAZY)) == NULL)
errx(1, "%s: %s", file, dlerror());
if ((datap = dlsym(handle, "data")) == NULL)
errx(1, "data: %s", dlerror());
if (*datap == ...)
...
if ((codep = dlsym(handle, "code")) == NULL)
errx(1, "code: %s", dlerror());
if ((*codep)(...) == ...)
...
if (dlclose(handle) != 0)
errx(1, "%s: %s", file, dlerror());
...
You almost always want to use -rdynamic to link an application that uses
dlopen(). Another commonly used linking feature is the run path, which
sets the directories that the dlopen() function will automatically check
at run time. To set the run path to /usr/contrib/lib/app, you would link
the application this way:
cc -rdynamic -Wl,-rpath,/usr/contrib/lib/app -o dlprog dlprog.o -ldl
SEE ALSOcc(1), ld(1), elf(5), ld.so(8)ACKNOWLEDGEMENTS
This dlopen() implementation is based on the Linux ld.so(8) implementa-
tion, which was primarily written by Eric Youngdale with help from Mitch
D'Souza, David Engel, Hongjiu Lu, Andreas Schwab and others.
BUGS
Unlike previous versions of dlopen() under BSD/OS, this version of
dlopen() cannot load relocatable object files. It will only load elf(5)
shared object files.
It is not possible to use the -static linking flag on an application that
uses dlopen(). Programs that use the dynamic linking library must be dy-
namically linked.
BSDI BSD/OS February 9, 1998 3