dlopen(3DL) (man pages section 3: Basic Library Functions)

man pages section 3: Basic Library Functions

dlopen(3DL)

NAME

dlopen, dlmopen– gain access to an executable object file

SYNOPSIS

cc [ flag... ] file... -ldl [ library... ]
#include <dlfcn.h>
#include <link.h>

pathname

mode

lmid

pathname

mode

DESCRIPTION

The dlopen() function makes an executable object file available to a running process. It returns to the process a handle that the process can use on subsequent calls to dlsym(3DL), dladdr(3DL), dlinfo(3DL), and dlclose(3DL). The value of this handle should not be interpreted in any way by the process. The pathname argument is the path name of the object to be opened. A path name containing an embedded '/' is interpreted as an absolute path or relative to the current directory. Otherwise, the set of search paths currently in effect by the runtime linker are used to locate the specified file. See NOTES.

The dlopen() function also loads any dependencies recorded within pathname. These dependencies are searched in the order in which they were loaded to locate any additional dependencies. This process continues until all the dependencies of pathname are loaded. This dependency tree is referred to as a group.

If the value of pathname is 0, dlopen() provides a handle on a set of global symbol objects. These objects consist of the original program image file, any dependencies loaded at program startup, and any objects loaded using dlopen() with the RTLD_GLOBAL flag. Because the latter set of objects can change during process execution, the set identified by handle can also change dynamically.

The mode argument describes how dlopen() operates on pathname with respect to the processing of reference relocations. The mode also affects the scope of visibility of the symbols provided by pathname and its dependencies. This visibility can affect how the resulting handle is used.

When an object is loaded, it can contain references to symbols whose addresses are not known until the object is loaded. These references must be relocated before the symbols can be accessed. References are categorized as either immediate or lazy. Immediate references are typically references to data items used by the object code. Immediate references include pointers to functions and calls to functions made from position-dependent shared objects. Lazy references are typically calls to global functions made from position-independent shared objects. The mode argument governs when these references take place and can be one of the following values:

RTLD_LAZY: Only immediate symbol references are relocated when the object is first loaded. Lazy references are not relocated until a given function is called for the first time. This value for mode should improve performance, since a process might not require all lazy references in any given object. This behavior mimics the normal loading of dependencies during process initialization. See NOTES.
RTLD_NOW: All necessary relocations are performed when the object is first loaded. This process might waste some processing if relocations are performed for lazy references that are never used. However, this mode ensures that when an object is loaded, all symbols referenced during execution are available. This behavior mimics the loading of dependencies when the environment variable LD_BIND_NOW is in effect.

See the Linker and Libraries Guide for more information about symbol references.

The visibility of symbols available for relocation can be affected by mode. To specify the scope of visibility for symbols loaded with a dlopen() call, mode should be a bitwise-inclusive OR with one of the following values:

RTLD_GLOBAL: The object's global 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 RTLD_GLOBAL to be searched.
RTLD_LOCAL: The object's globals symbols are only available for the relocation processing of other objects that comprise the same group.

The program image file and any objects loaded at program startup have the mode RTLD_GLOBAL. The mode RTLD_LOCAL is the default mode for any objects acquired with dlopen(). A local object can be a dependency of more then one group. Any object of mode RTLD_LOCAL that is referenced as a dependency of an object of mode RTLD_GLOBAL is promoted to RTLD_GLOBAL. In other words, the RTLD_LOCAL mode is ignored.

Any object loaded by dlopen() that requires relocations against global symbols can reference the symbols in any RTLD_GLOBAL object. Objects of this mode are at least the program image file and any objects loaded at program startup. A loaded object can also reference symbols from itself, and from any dependencies the object references. However, the mode parameter can also be a bitwise–inclusive OR with one of the following values to affect the scope of symbol availability:

RTLD_GROUP: Only symbols from the associated group are made available for relocation. A group is established from the defined object and all the dependencies of that object. A group must be completely self-contained. All dependency relationships between the members of the group must be sufficient to satisfy the relocation requirements of each object that comprises the group.
RTLD_PARENT: The symbols of the object initiating the dlopen() call are made available to the objects obtained by dlopen() itself. This option is useful when hierarchical dlopen() families are created. Although the parent object can supply symbols for the relocation of this object, the parent object is not available to dlsym() through the returned handle.
RTLD_WORLD: Only symbols from RTLD_GLOBAL objects are made available for relocation.

The default modes for dlopen() are both RTLD_WORLD and RTLD_GROUP. If an object is required by different dependencies specifying differing modes, the mode parameter can be the bitwise-inclusive OR of these default modes.

The following modes provide additional capabilities outside of relocation processing:

RTLD_NODELETE: The specified object is tagged to prevent its deletion from the address space as part of a dlclose().
RTLD_NOLOAD: The specified object is not loaded as part of the dlopen(). However, a valid handle is returned if the object already exists as part of the process address space. Additional modes can be specified as a bitwise–inclusive OR with the present mode of the object and its dependencies. The RTLD_NOLOAD mode provides a means of querying the presence or promoting the modes of an existing dependency.

The default use of a handle with dlsym() allows a symbol search to inspect all objects associated with the group of objects loaded from dlopen(). The mode parameter can also be a bitwise–inclusive OR with the following value to restrict this symbol search:

RTLD_FIRST: Use of this handle with dlsym(), restricts the symbol search to the first object associated with the handle.

An object can be accessed from a process both with and without RTLD_FIRST. Although the object will only be loaded once, two different handles are created to provide for the different dlsym() requirements.

The dlmopen() function is identical to dlopen(), except that an identifying link-map ID (lmid) is provided. This link-map ID informs the dynamic linking facilities upon which link-map list to load the object. See the Linker and Libraries Guide for details about link-maps.

The lmid passed to dlmopen() identifies the link-map list on which the object is loaded. This parameter can be any valid Lmid_t returned by dlinfo() or one of the following special values:

LM_ID_BASE: Load the object on the applications link-map list.
LM_ID_LDSO: Load the object on the dynamic linkers (ld.so.1) link-map list.
LM_ID_NEWLM: Cause the object to create a new link-map list as part of loading. Objects opened on a new link-map list must have all of their dependencies expressed. There are no other objects on the link-map to compensate for unexpressed dependencies.

RETURN VALUES

The dlopen() function returns NULL if pathname cannot be found, cannot be opened for reading, or is not a shared object or a relocatable object. It also returns NULL if an error occurs during the process of loading pathname or relocating its symbolic references. See NOTES. Additional diagnostic information is available through dlerror().

USAGE

The dlopen() and dlmopen() functions are members of a family of functions that give the user direct access to the dynamic linking facilities. This family of functions is available only to dynamically-linked processes. See the Linker and Libraries Guide.

ATTRIBUTES

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Standard
MT-Level	MT-Safe

NOTES

If pathname has dependencies on other objects, these objects are automatically loaded by dlopen(). The directory search path used to find pathname and any dependencies may be affected by setting the environment variable LD_LIBRARY_PATH. Any LD_LIBRARY_PATH variable is analyzed once at process startup. The search path may also be affected from a runpath setting within the object from which the call to dlopen() originates. These search rules will only be applied to path names that do not contain an embedded '/'. Objects whose names resolve to the same absolute path name or relative path name may be opened any number of times using dlopen(). However, the object referenced will only be loaded once into the address space of the current process.

When loading shared objects, the application should open a specific version of the shared object. Do not rely on the version of the shared object pointed to by the symbolic link.

When building objects to be loaded on a new link-map list, some precautions need to be taken. In general, all dependencies must be included when building an object. Also, include /usr/lib/libmapmalloc.so.1 before /usr/lib/libc.so.1 when building an object.

When an object is loaded on a new link-map list, it is isolated from the main running program. There are certain global resources that are only usable from one link-map list. A few examples of these are the sbrk() based malloc(), libthread(), and the signal vectors. Because of this, care must be taken not to use any of these resources other than from the primary link-map list. These issues are discussed in further detail in the Linker and Libraries Guide.

Some symbols defined in dynamic executables or shared objects may not be available to the runtime linker. The symbol table created by ld for use by the runtime linker might contain only a subset of the symbols defined in the object.

As part of loading a new object, initialization code within the object is called before the dlopen() returns. This initialization is user code, and as such, may produce errors that can not be caught by dlopen(). For example, an object loaded using RTLD_LAZY that attempts to call a function that can not be located results in process termination. Erroneous programming practices within the initialization code can also result in process termination. The runtime linkers debugging facility can offer help identifying these types of error. See the LD_DEBUG environment variable of ld.so.1(1).

SunOS 5.9 Last Revised 25 Oct 2002