DLL Programmer's Guide for TNS/R Systems

Dynamic Use of DLLs
DLL Programmer’s Guide for TNS/R Systems—522203-002
3-6
Closing a Running Loadfile’s Handle to a DLL
(dlclose)
When dlsym returns 0, call dlerror() for a textual description of the error, or
dlresultcode() for an encoded error code and error-detail. In the rare event that dlsym
found the symbol and its value was 0, dlerror() and dlresultcode() return 0.
Closing a Running Loadfile’s Handle to a DLL
(dlclose)
To invalidate a handle obtained by a dlopen call, a running process issues the following
call.
int dlclose(dlhandle dlopen_handle)
dlclose invalidates the handle and makes it unavailable for any other call that uses that
handle. If the specified handle is the last outstanding one for the referenced DLL and if
that DLL was dynamically loaded (by dlopen), the DLL is also unloaded. The following
is the parameter of a dlclose call:
*dlopen_handle is a handle previously returned by a dlopen call.
Closing the last handle for the main program or for any DLLs that were loaded with the
main program does not unload any of these loadfiles. Also, if dlclose causes a loadfile
to be unloaded, then any DLL in its load set is also unloaded, unless that DLL also
belongs to the load set of the main program or to a DLL that still has an outstanding
handle for it. When dlclose unloads DLLs, the new operating load set becomes the old
operating load set less the unloaded DLLs.
Referencing code or data in a DLL using a handle that has been invalidated by dlclose
produces undefined results.
Issuing a dlopen that specifies a DLL previously unloaded by dlclose reloads that DLL
plus the libraries in its libList that are not already loaded, and establishes a new handle
to it.
Returned Values of dlclose
dlclose returns 0 if it successfully invalidated the specified handle.
Error-Return Values of dlclose
If dlclose cannot invalidate the specified handle, it returns a non-zero number. In that
event, call dlerror() for a textual description of that error, or dlresultcode() for
an encoded error code and error-detail.