dllfree() — Free the supplied dynamic link library

Standards

Standards / Extensions	C or C++	Dependencies
C Library	both

Format

#include <dll.h>

int dllfree(dllhandle *dllHandle);

General description

Frees the supplied dynamic link library (DLL). It also deletes the DLL from memory if the handle was the last handle accessing the DLL.

Returned value

dllfree() returns one of the following values and set errno if the return code is not 0:

Value: Meaning
0: Successful
1: The dllHandle supplied is NULL or dllhandle is inactive.
2: There are no DLLs to be deleted.
3: DLL is not physically deleted because there is another dllHandle for this DLL or there is an implicit reference to the DLL.
4: Delete of DLL failed.
5: No match is found for input dllHandle.
6: Not supported under this environment.
7: C++ destructors are currently running for this DLL. A dllfree() is already in progress.
8: The handle passed to dllfree() was obtained from dlopen().

Usage notes

This function is deprecated; use dlclose() instead.
This function is not available under SPC, MTF and CSP environments.
If a DLL is loaded implicitly, it cannot be deleted with dllfree(). For more information on the implicit use of DLLs, see z/OS XL C/C++ Programming Guide.
DLLs that are loaded explicitly, that is with dllload(), and are not freed with a corresponding call to dllfree(), are freed automatically at enclave termination in LIFO sequence.
C++ destructors are executed only once, when the DLL load module is physically deleted.
More detailed diagnostic information is available through the _EDC_DLL_DIAG environment variable, and the Language Environment® DLL Failure control block (CEEDLLF) chain. The default action is to issue an error message to the Language Environment message file.

Example

CELEBDL4

⁄* CELEBDL4

   The following example shows how to use dllfree() to free the
   dllhandle for the DLL stream.

 *⁄
#include <stdio.h>
#include <dll.h>
#include <stdlib.h>

int main() {
    dllhandle *handle;
    char *name="stream";
    int (*fptr1)(int);
    int (*fptr)(int);
    int *ptr_var1;
    int *ptr_var;
    int rc=0;

    handle = dllload(name); ⁄* call to stream DLL *⁄
    if (handle == NULL) {
       perror("failed on call to stream DLL");
       exit(-1);
    }

    fptr1 = (int (*)(int)) dllqueryfn(handle,"f1");
    ⁄* retrieving f1 function *⁄
    if (fptr == NULL) {
       perror("failed on retrieving f1 function");
       exit(-2);
    }

    ptr_var = dllqueryvar(handle,"var1");
    ⁄* retrieving var1 variable *⁄
    if (ptr_var1 == NULL) {
       perror("failed on retrieving var1 variable");
       exit(-3);
    }

    rc = fptr(*ptr_var1); ⁄* execute DLL function f1 *⁄
    *ptr_var++;           ⁄* increment value of var1 *⁄

    rc = dllfree(handle); ⁄* freeing handle to stream DLL *⁄
    if (rc != 0) {
       perror("failed on dllfree call");
    }
    return (0);
}