Guardian Native C Library Calls Reference Manual (G06.28+, H06.04+)

dlclose(3) Guardian Native C Library Calls Reference Manual
NAME
dlclose - Invalidates a dynamic-link library handle and unloads any dynamically loaded library
LIBRARY
G-series native Guardian processes: $SYSTEM.SYSnn.ZRLDSRL
G-series native OSS processes: /G/system/sysnn/zrldsrl
H-series native Guardian processes: $SYSTEM.ZDLLnnn.ZRLDDLL
H-series OSS processes: /G/system/zdllnnn/zrlddll
SYNOPSIS
#include <dlfcn.h>
int dlclose (
dlHandle dlopen_handle );
PARAMETERS
dlopen_handle Specifies a currently valid library handle previously returned by a call to the
dlopen() function
DESCRIPTION
The dlclose() function invalidates the library handle designated by the dlopen_handle value. It
unloads any libraries that are no longer required.
In the simplest case, dlclose() unloads any library loaded by the dlopen( ) invocation that
returned the destroyed library handle. When there are linkages between libraries loaded by
separate dlopen( ) calls, a library loaded by one call might be required by a library loaded by
another call, and might be unloaded by a subsequent call to dlclose() specifying another library
handle.
dlclose() does not unload the main program or libraries that were loaded with the main program.
When dlclose() invalidates a library handle, it decrements the usage count for the library loaded
by the dlopen() invocation that returned the destroyed handle, and for any libraries that library
required. dlclose() unloads any dynamically loaded libraries that have become unused.
Once a library has been unloaded by dlclose(), referencing addresses where the library text and
data were loaded results in undefined behavior.
NOTES
The rld dynamic loader is an unprivileged interface; it cannot be invoked from a program or
DLL that is licensed or has callable functions, or from a program with a priv entry point. Process
creation fails if such a file refers to dlopen( ), dlsym( ), dlclose(), dlerror(),ordlresultcode().
Depending upon the circumstances, process-creation error/detail value combinations of 77,11 or
78,7 can result.
EXAMPLES
Suppose that library A requires library C (because C is specified on the libList of A). Suppose
that library B also requires library C. Consider the following program:
hA = dlopen("A", ...); // loads A and C; links A to C.
hB = dlopen("B", ...); // loads B; links B to already-loaded C
if (perverse) { // close in order of opening
dlclose(hA); // unloads A but not C
dlclose(hB); // unloads B and C
}
else { // close in inverse order of opening
dlclose(hB); // unloads B
dlclose(hA); // unloads A and C
}
1−48 Hewlett-Packard Company 527192-005