dlclose(3)dlclose(3)NAMEdlclose - close a dlopen() object
SYNOPSIS
#include <dlfcn.h>
int dlclose(
void *handle );
PARAMETERS
Specifies a pointer to a global symbol object that is returned from a
call to dlopen().
DESCRIPTION
The dlclose() function 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.
The use of dlclose() reflects a statement of intent on the part of the
process, but does not create any requirements on the dynamic library
loader, such as removal of the code or symbols referenced by handle.
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.
The dlclose() function deallocates the address space for the library
corresponding to handle. The results are undefined if any user func‐
tion continues to call a symbol resolved in the address space of a
library that has since been deallocated by dlclose().
The dlclose() operation will not remove an object to which references
have been relocated, until or unless all such references are removed.
For instance, an object that had been loaded with a dlopen() operation
specifying the RTLD_GLOBAL option might provide a target for dynamic
relocations performed in the processing of other objects -- in such
environments, an application may assume that no relocation, once made,
will be undone or remade unless the object requiring the relocation has
itself been removed.
NOTES
The dlopen() and dlclose() routines might dynamically change the reso‐
lution of certain symbols referenced by a program or its shared library
dependencies. The dlopen() routine might resolve symbols that were
previously unresolved, and dlclose() might cause resolved symbols to
become unresolved or to be reresolved to a different symbol definition.
A portable application will employ a handle returned from a dlopen()
invocation only within a given scope bracketed by the dlopen() and
dlclose() operations. The dynamic library loader is free to use refer‐
ence counting or other techniques such that multiple calls to dlopen()
referencing the same object may return the same object for handle. The
dynamic library loader is also free to re-use a handle. For these rea‐
sons, the value of a handle must be treated as an opaque object by the
application, used only in calls to dlsym() and dlclose().
ERRORS
No errors are defined.
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. More detailed diagnos‐
tic information is available through dlerror().
SEE ALSOdlerror(3), dlopen(3), dlsym(3)dlclose(3)