dlopen() — Gain access to a dynamic link library

Standards

Standards / Extensions C or C++ Dependencies

Single UNIX Specification, Version 3

 both z/OS® V1R6

Format

#define _UNIX03_SOURCE
#include <dlfcn.h>

void  *dlopen(const char *file, int mode);

General description

Makes the dynamic link library (DLL) specified by file available to the calling program.

If the file argument contains a single slash ("/"), it is used as the z/OS UNIX file system path name for the DLL. If the environment variable LIBPATH is set, each directory listed will be searched for the DLL. Otherwise, the current directory will be searched.
Note: Searching for a DLL in the z/OS UNIX file system is case-sensitive.

If the file argument begins with two slashes ("//"), then an attempt is made to load the DLL from the caller's MVS™ load library search order (in order: STEPLIB/JOBLIB, LPA, Link List). The DLL name must be eight characters or less, and is converted to uppercase.

If the file argument doesn't begin with one or two slashes ("/" or "//"), and doesn't contain a single slash ("/") anywhere in the name, then it is ambiguous as to where the DLL resides.
  • If the POSIX(ON) runtime option is specified, then the z/OS UNIX file system is searched first for the DLL, and if not found, the MVS load library is searched.
  • If the POSIX(OFF) runtime option is specified, then the MVS load library is searched first for the DLL, and if not found, the z/OS UNIX file system is searched.

Under the CICS® environment, the search sequence for DLL load modules is the same as that used for dynamically loaded CICS modules. Loading DLLs from the z/OS UNIX file system is not supported under CICS.

For more information about how DLLs are loaded and how the search sequence is used, see the topic about in z/OS Language Environment Programming Guide.

A successful call returns a handle which the caller may use on subsequent calls to dlsym() and dlclose(). The value of this handle should not be interpreted in any way by the caller.

Only a single copy of a DLL is brought into the address space, even if invoked multiple times for the same DLL, and even if different values of the file parameter are used to reference the same DLL.

The mode parameter describes how dlopen() operates on a file with respect to the processing of dependent DLLs and the scope of visibility of the symbols provided within file. If a file is specified in multiple invocations, mode is interpreted at each invocation. The mode is a bitwise-OR of the values specified.

Mode Values

When a DLL is loaded, it may contain implicit references to symbols in another "dependent" DLL, whose addresses are not known until that DLL is loaded. These implicit references must be relocated before the symbols can be accessed, which means loading the DLL containing the references. The mode parameter governs when these relocations (and loads) take place and may have the following values:
Value
Description
RTLD_LAZY
When possible, the loading of dependent DLLs, and resolution of symbols contained therein, may be deferred until the first reference to one of those symbols. This is the default behavior.
Note: Once RTLD_NOW has been specified, all relocations will have been completed causing additional RTLD_NOW operations to be redundant and any further RTLD_LAZY operations irrelevant.
RTLD_NOW
Load all dependent DLLs for the DLL being loaded and resolve all symbols before returning. This may include zero or more levels of nested dependent DLLs, all of which are loaded at this time.
RTLD_GLOBAL
Allows symbols in the DLL being loaded to be visible when resolving symbols through the global symbol object that was opened with dlopen(NULL,0). All dependent DLLs are always implicitly loaded as if RTLD_GLOBAL had been specified. This is the default behavior.
RTLD_LOCAL
Prevents symbols in the DLL being loaded to be visible when resolving symbols through the global symbol object that was opened with dlopen(NULL,0). All dependent DLLs of this DLL continue to be implicitly loaded as if RTLD_GLOBAL had been specified.

If a subsequent call is made for this same DLL with a mode of RTLD_GLOBAL, then the DLL will maintain the RTLD_GLOBAL status regardless of any previous or future specification of RTLD_LOCAL, as long as the DLL remains loaded (see dlclose()).

If the value of file is NULL, dlopen() returns a "global symbol object" handle. This object will provide access (via dlsym()) to the symbols exported from:

Symbols introduced by the call to dlopen() for a DLL, and available through dlsym(), are those which are exported by the DLL. Typically such symbols will be those identified by a #pragma export in C, or with the EXPORTALL compile option. For details on how to specify exported data and functions, for C/C++ as well as other languages, see the topic about building a simple DLL in z/OS Language Environment Programming Guide

Returned value

NULL is returned if:
  • file cannot be found or opened for reading
  • file is not in correct DLL executable format
  • an error occurred during the process of loading file, or relocating its symbolic references

Usage notes

  1. For details on how to create and use DLLs, see z/OS Language Environment Programming Guide.
  2. The AMODE of the application must be the same as the AMODE of the DLL.
  3. Non-local C++ static constructors defined in a DLL are executed only once, when the DLL program object is physically loaded into memory.
  4. More detailed diagnostic information is available through dlerror(), the _EDC_DLL_DIAG environment variable, and the Language Environment® DLL Failure control block (CEEDLLF) chain.
  5. This function is not available under SPC, MTF and CSP environments.

Example

The following example illustrates use of dlopen() and dlclose():

...
/* Open a dynamic library and then close it ... */

#include <dlfcn.h>

void *mylib;
int eret;

mylib = dlopen("mylib.so", RTLD_LOCAL | RTLD_LAZY);
...
eret = dlclose(mylib);
...

Related information

Parent topic: Library functions