dlopen() — Gain access to a dynamic link library
|Standards / Extensions||C or C++||Dependencies|
Single UNIX Specification, Version 3
#define _UNIX03_SOURCE #include <dlfcn.h> void *dlopen(const char *file, int mode);
Makes the dynamic link library (DLL) specified by file available to the calling program.
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 8 characters or less, and is converted to uppercase.
/) or two slashes (
//, 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 can 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 regarding the processing of dependent DLLs and the scope of visibility of the symbols that are 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.
- When possible, the loading of dependent DLLs, and resolution of symbols contained therein, might
be deferred until the first reference to one of those symbols. This is the default behavior.
Note: After RTLD_NOW is specified, all relocations will have been completed causing additional RTLD_NOW operations to be redundant and any further RTLD_LAZY operations irrelevant.
- 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.
- 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.
- 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 provides access (via dlsym()) to the symbols exported from:
- The main application and dependent DLLs for the main application that were loaded at program start-up, and
- The set of DLLs loaded using dlopen() with the RTLD_GLOBAL flag. This set of DLLs can change dynamically as other DLLs are opened and closed.
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.
- 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.
- Error Code
- A 64-bit caller tried to load a 31-bit DLL.
- A 31-bit caller tried to load a 64-bit DLL.
- For details on how to create and use DLLs, see z/OS Language Environment Programming Guide.
- The AMODE of the application must be the same as the AMODE of the DLL.
- Non-local C++ static constructors defined in a DLL are executed only once, when the DLL program object is physically loaded into memory.
- More detailed diagnostic information is available through dlerror(), the _EDC_DLL_DIAG environment variable, and the Language Environment® DLL Failure control block (CEEDLLF) chain.
- This function is not available under SPC, MTF and CSP environments.
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); ...