man Pages(3): Library Routines

dlopen(3X)

NAME

dlopen, dlmopen- gain access to an executable object file

SYNOPSIS

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

pathname

mode

lmid

pathname

mode

DESCRIPTION

dlopen() and dlmopen() are members of a family of routines that give the user direct access to the dynamic linking facilities. (See Linker and Libraries Guide ). These routines are made available through the library loaded when the option -ldl is passed to the link-editor.

Note: These routines are available to dynamically-linked processes ONLY.

dlopen() makes an executable object file available to a running process. dlopen() returns to the process a handle which the process may use on subsequent calls to dlsym() and dlclose(). The value of this handle should not be interpreted in any way by the process. pathname 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 will be used to locate the specified file. See NOTES below.

Any dependencies recorded within pathname are also loaded as part of the dlopen(). These dependencies are searched, in the order they are loaded, to locate any additional dependencies. This process will continue 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 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 dependencies loaded at program startup, and any objects that were loaded using dlopen() together with the RTLD_GLOBAL flag. As the latter set of objects can change during process execution, the set identified by handle can also change dynamically.

dlmopen() is identical to the dlopen() routine, except that an identifying link-map id (lmid) is passed into it. This link-map id informs the dynamic linking facilities upon which link-map list to load the object. See Linker and Libraries Guide

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

RTLD_LAZY: Only references to data symbols are relocated when the object is first loaded. References to functions are not relocated until a given function is invoked for the first time. This mode should improve performance, since a process may not reference all of the functions in any given object. This behavior mimics the normal loading of dependencies during process initialization.
RTLD_NOW: All necessary relocations are performed when the object is first loaded. This may waste some processing, if relocations are performed for functions that are never referenced. This behavior may be useful for applications that need to know as soon as an object is loaded that all symbols referenced during execution will be available. This option mimics the loading of dependencies when the environment variable LD_BIND_NOW is in effect.

To determine the scope of visibility for 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 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 may 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 will be 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, which are at least the program image file and any objects loaded at program startup, from the object itself, and from any dependencies the object references. However, the mode parameter may also be bitwise or'ed with 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. Note that 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. These modes are or'ed together if an object is required by different dependencies specifying differing modes.

The following modes provide additional capabilities outside of relocation processing:

RTLD_NODELETE: The specified object will not be deleted from the address space as part of a dlclose().
RTLD_NOLOAD: The specified object is not loaded as part of the dlopen(), but a valid handle is returned if the object already exists as part of the process address space. Additional modes can be specified and will be or'ed 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 lmid passed to dlmopen() identifies the link-map list where the object will be loaded. This 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: Causes the object to create a new link-map list as part of loading. It is vital that any object opened on a new link-map list have all of its dependencies expressed because there will be no other objects on this link-map.

RETURN VALUES

If pathname cannot be found, cannot be opened for reading, is not a shared or relocatable object, or if an error occurs during the process of loading pathname or relocating its symbolic references, dlopen() will return NULL. More detailed diagnostic information will be available through dlerror().

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
MT-Level	MT-Safe

NOTES

If other objects were link-edited with pathname when pathname was built, that is, the pathname has dependencies on other objects, those objects will automatically be loaded by dlopen(). The directory search path used to find both pathname and the other needed objects may be affected by setting the environment variable LD_LIBRARY_PATH, which is analyzed once at process startup, and from a runpath setting within the object from which the call to dlopen() originated. These search rules will only be applied to path names that do not contain an embedded '/'. Objects whose names resolve to the same absolute 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, as opposed to relying on the version of the shared object pointed to by the symbolic link.

When building objects that are to be loaded on a new link-map list (see LM_ID_NEWLM), 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 into memory 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 would be the sbrk() based malloc(), libthread(), and the signal vectors. Because of this, care must be taken not to use any of these resources on any but 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.

SunOS 5.7 Last Revised 19 Mar 1997