Syntax
#include <dlfcn.h> |
int dlclose(void *handle); |
dlclose() can also be called in an ASCII environment using identical syntax. An own ASCII variant is not necessary since dlclose() uses no strings.
Description
dlclose() is used to inform the system that the object referenced by a handle returned from a previous dlopen() invocation is no longer needed by the application.
Once an object has been closed using dlclose(), an application should assume that its symbols are no longer available to dlsym(). All objects loaded automatically as a result of invoking dlopen() on the referenced object are also closed.
Return value
If the referenced object was successfully closed, dlclose() returns 0.
If the object could not be closed, or if handle does not refer to an open object, dlclose() returns a non-zero value.
The errno variable is not set. An error message (diagnostic information) will be available through dlerror().
Application usage
The application should employ a handle returned from a dlopen() invocation only within a given scope bracketed by the dlopen() and dlclose() operations. Multiple calls to dlopen() referencing the same object may return the same object for handle. Applications are also free to re-use a handle. For these reasons, the value of a handle must be treated as an opaque object by the application, used only in calls to dlsym() and dlclose().
For C++, language-specific finalizations are performed when the shared object is closed:
dlclose() marks the addressed shared object as being no longer accessible. The object is only physically unloaded if there are no other shared objects which have or could have references to this object.
Example
The following example illustrates how dlclose() can be used.
void *handle;
int ret;
/* Close the object */
if ((ret = dlclose(handle)) != 0) {
printf (error during dlclose, ret: %d dlerror: %s\n”, ret, dlerror());
exit(EXIT_FAILURE);
}
See also
dlerror(), dlopen(), dlsym()