DLOPEN(3X)

NAME
dlopen, dlsym, dlerror, dlclose - simple programmatic interface to the dynamic linker

SYNOPSIS
#include <dlfcn.h>

void *dlopen(path, mode)
char *path; int mode;

void *dlsym(handle, symbol)
void *handle; char *symbol;

char *dlerror()

int dlclose(handle);
void *handle;

DESCRIPTION

These functions provide a simple programmatic interface to the services of the dynamic link-editor. Operations are provided to add a new shared object to an program's address space, obtain the address bindings of symbols defined by such objects, and to remove such objects when their use is no longer required.

dlopen() provides access to the shared object in path, returning a descriptor that can be used for later references to the object in calls to dlsym() and dlclose(). If path was not in the address space prior to the call to dlopen(), then it will be placed in the address space, and if it defines a function with the name _init that function will be called by dlopen(). If, however, path has already been placed in the address space in a previous call to dlopen(), then it will not be added a second time, although a count of dlopen() operations on path will be maintained. mode is an integer containing flags describing options to be applied to the opening and loading process — it is reserved for future expansion and must always have the value 1. A null pointer supplied for path is interpreted as a reference to the “main” executable of the process. If dlopen() fails, it will return a null pointer.

dlsym() returns the address binding of the symbol described in the null-terminated character string symbol as it occurs in the shared object identified by handle. The symbols exported by objects added to the address space by dlopen() can be accessed only through calls to dlsym(), such symbols do not supersede any definition of those symbols already present in the address space when the object is loaded, nor are they available to satisfy “normal” dynamic linking references. dlsym() returns a null pointer if the symbol can not be found. A null pointer supplied as the value of handle is interpreted as a reference to the executable from which the call to dlsym() is being made — thus a shared object can reference its own symbols.

dlerror returns a null-terminated character string describing the last error that occurred during a dlopen(), dlsym(), or dlclose(). If no such error has occurred, then dlerror() will return a null pointer. At each call to dlerror(), the “last error” indication will be reset, thus in the case of two calls to dlerror(), and where the second call follows the first immediately, the second call will always return a null pointer.

dlclose() deletes a reference to the shared object referenced by handle. If the reference count drops to 0, then if the object referenced by handle defines a function _fini, that function will be called, the object removed from the address space, and handle destroyed. If dlclose() is successful, it will return a value of 0. A failing call to dlclose() will return a non-zero value.

The object-intrinsic functions _init and _fini are called with no arguments and treated as though their types were void.

These functions are obtained by specifying -ldl as an option to ld(1).

SEE ALSO
ld(1), link(5)