dlopen - gain access to a shared object file

Syntax

#include <dlfcn.h>

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

The function __dlopen_ascii() with the same parameters must be used for the call in an ASCII environment.

Description

dlopen() makes a shared object file specified by file available to the calling program.

A successful dlopen() 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.

file is used to construct a pathname to the object file:

• If file is beginning with a slash character, the file argument is used as the complete filename.
• If file does not begin with a slash character, the variable LD_LIBRARY_PATH is used to generate the complete filename together with file. LD_LIBRARY_PATH contains a list of directories (absolute or also relative path names) separated by a colon. If this list is empty, the current working directory is used.
• If the value of file is 0, dlopen() provides a handle on a global symbol object. This object provides access to the symbols from an ordered set of objects consisting of the original program image file, together with any objects loaded at program startup and the set of objects loaded using a dlopen() operation together with the RTLD_GLOBAL flag. As the latter set of objects can change during execution, the set identified by handle can also change dynamically.

The mode parameter describes how dlopen() will operate upon file with respect to the processing of relocations and the scope of visibility of the symbols provided within file. When an object is brought into the address space of a process, it may contain references to symbols whose addresses are not known until the object is loaded. These references must be resolved before the symbols can be accessed. The mode parameter governs when these relocations take place and may have the following values:

RTLD_LAZY

The same behavior as RTLD_NOW.

RTLD_NOW

All necessary relocations are performed when the object is first loaded. Each shared object together with its dependent objects is loaded in a link-and-load context of its own. In case of unresolved relocations no warning is sent; dlopen() does not end with an error.

Any object loaded by dlopen() that requires relocations against global symbols can reference the symbols in the original process image file, any objects loaded at program startup, from the object itself as well as any other object included in the same dlopen() invocation, and any objects that were loaded in any dlopen() invocation and which specified the RTLD_GLOBAL flag.

To determine the scope of visibility for the symbols loaded with a dlopen() invocation, the mode parameter should be bitwise or'ed with one of the following values:

RTLD_GLOBAL

The object's symbols are made available for the relocation processing of any other object. In addition, symbol lookup using dlopen (0, mode) and an associated dlsym() allows objects loaded with this mode to be searched.

RTLD_LOCAL

The object's symbols are not made available for the relocation processing of any other object. 

If neither RTLD_GLOBAL nor RTLD_LOCAL is specified, then RTLD_LOCAL is default value.

Note that once RTLD_GLOBAL has been specified, the object will maintain the RTLD_GLOBAL status regardless of any previous or future specification of RTLD_LOCAL, so long as the object remains in the address space (see dlclose()). 

Symbols introduced into a program through calls to dlopen() may be used in relocation activities, for example. Symbols so introduced may duplicate symbols already defined by the program or previous dlopen() operations. 

The symbols introduced by dlopen() operations, and available through dlsym() are those that are of type ENTRY shown by a VSVI call.

Return value

dlopen() returns NULL in the following cases:

• file cannot be found.
• file cannot be opened for reading.
• The file object format is not dedicated (suitable) for processing by dlopen().
• An error occurs during the process of loading file or relocating its symbolic references.
• Unresolved external references were found. In this case, the shared object is not processed further.

The errno variable is not set. An error message (diagnostic information) will be available through dlerror().

If the entries are indicated repeatedly, no error message is returned (no NULL return value). In case of repeatedly indicated entries always the first entry is used.

If the environment variable LD_UNRESOLVED=YES is set, the shared onbjects will be processed further even and if any unresolved external links are found (no NULL return value).

The respective language-specific runtime system is loaded into the default context before the shared object is loaded, and initialized. To do this, the runtime system must be installed in BS2000 via IMON.

A message with the name and type of the external link (XDSECT, VCON or EXTERN) is output for each unresolved external link. Here up to 512 unresolved external links are taken into consideration. If there are more than 512 unresolved external links, a warning is also issued. In this way step-by-step corrections enable all unresolved external links to be found and resolved.

Example

The following example illustrates how dlopen() can be used.

void    *handle; 

/* Open the object*/
handle = dlopen("./mylib.so",RTLD_LAZY + RTLD_GLOBAL);
if (handle == NULL) {
    printf (error during dlopen, dlerror: %s\n”, dlerror());
    exit(EXIT_FAILURE);
}

See also

dlclose(), dlerror(), dlsym()