dlclose, dlerror, dlopen, dlsym - Programming interface to dynamic linking loader.
#include <dlfcn.h>
void *dlopen
(const char *filename, int
flag);
const char *dlerror(void);
void *dlsym(void *handle, char
*symbol);
int dlclose (void *handle);
dlopen loads a dynamic library from the file named by the null terminated string filename and returns an opaque "handle" for the dynamic library.
External references in the library are resolved using the libraries in that library’s dependency list.
flag may be either RTLD_GLOBAL in which case the external symbols defined in the library will be linked to any previously loaded versions of the symbol or RTLD_LOCAL in which case the external symbols defined in the library will receive their own instantiation separate from any previously loaded versions of the symbol. If the same library is loaded multiple times with dlopen(), The dl software maintains link counts for the library, so a dynamic library is not deallocated until dlclose has been called on it as many times as dlopen has succeeded on it.
If dlopen fails for any reason, it returns NULL. A human readable string describing the most recent error that occurred from any of the dl routines (dlopen, dlsym or dlclose) can be extracted with dlerror(). dlerror returns NULL if no errors have occurred since initialization or since it was last called. (Calling dlerror() twice consecutively, will always result in the second call returning NULL.)
dlsym takes a "handle" of a dynamic library returned by dlopen and the null terminated symbol name, returning the address where that symbol is loaded. If the symbol is not found, dlsym returns NULL; however, the correct way to test for an error from dlsym is to save the result of dlerror into a variable, and then check if saved value is not NULL. This is because the value of the symbol could actually be NULL. It is also necessary to save the results of dlerror into a variable because if dlerror is called again, it will return NULL.
dlclose decrements the reference count on the dynamic library handle handle. If the reference count drops to zero and no other loaded libraries use symbols in it, then the dynamic library is unloaded.
Load the math library, and print the cosine of 2.0:
#include <dlfcn.h>
int main(int
argc, char **argv) {
void *handle = dlopen ("/lib/libm.so",
RTLD_LOCAL);
double (*cosine)(double) = dlsym(handle, "cos");
printf ("%f\n", (*cosine)(2.0));
dlclose(handle);
}
If this program were in a file named "foo.c", you would build the program with the following command:
cc -o foo foo.c -ldl
Do the same thing, but check for errors at every step:
#include <stdio.h>
#include <dlfcn.h>
int main(int
argc, char **argv) {
void *handle;
double (*cosine)(double);
char *error;
handle = dlopen
("/lib/libm.so", RTLD_LOCAL);
if (!handle) {
fputs (dlerror(), stderr);
exit(1);
}
cosine =
dlsym(handle, "cos");
if ((error = dlerror()) != NULL) {
fputs(error, stderr);
exit(1);
}
printf
("%f\n", (*cosine)(2.0));
dlclose(handle);
}
The dlopen interface standard comes from Solaris.
ld(1),