dlclosehandle

dlclosehandle is an informal term used to describe the opaque handle returned by a dynamic loading API (most commonly the handle returned by dlopen). In standard POSIX dynamic linking, this library handle identifies a loaded shared object within a process and is used to locate symbols with dlsym and to unload the object with dlclose. The handle itself is not defined to have a particular structure in code; it is treated as an opaque value that the dynamic linker understands.

Obtaining and using a handle typically involves calling dlopen with the path to a shared library and a set of flags (for example, RTLD_LAZY or RTLD_NOW). If dlopen succeeds, it returns a non-null handle that you store and later pass to dlsym to resolve symbols and to dlclose to request unloading. If it fails, dlerror provides a human-readable message. The handle may refer to the entire object or to a specific loaded image, depending on platform and loader behavior.

Unloading and safety considerations are important. Calling dlclose with the handle decrements the loader’s reference count for the object. The library may be unloaded when the count reaches zero, which can invalidate any function pointers or data pointers obtained through dlsym. Using symbols after dlclose can lead to undefined behavior. Some platforms offer flags such as RTLD_NODELETE to alter unloading behavior, but portability and correctness require ensuring no outstanding references remain when unloading.

Terminology and portability: dlclosehandle is not an official API name; the official terms are library handle or opaque handle. The standard functions involved are dlopen, dlsym, and dlclose; behavior and exact semantics can vary slightly across Unix-like systems.