ChorusOS man pages section 2K: Kernel System Calls

dlopen(2K)

NAME

dlopen- gain access to a dynamic object file

SYNOPSIS

#include <cx/dlfcn.h>

pathname

mode

API RESTRICTIONS

The function or functions documented here may not be used safely in all application contexts with all APIs provided in the ChorusOS 5.0 product.

See API(5FEA) for details.

FEATURES

DYNAMIC_LIB

DESCRIPTION

dlopen() is a member of the dynamic linking API, a family of routines that give the user direct access to dynamic linking functionality.

Note -

dlopen() is only available to programs and libraries compiled with imake rules of the form DynamicTypeTarget(), where Type is one of User, Sup, CXXUser, CXXSup or Library.

See the ChorusOS 5.0 Application Developer's Guide for more information on building executables with dynamic libraries.

dlopen() makes a dynamic object file available to a running actor. dlopen() returns a handle that an actor may use when calling dlsym() and dlclose().

PARAMETERS

The value of the handle should not be interpreted in any way by the actor. The pathname is the path name of the object to be opened. Any pathname containing "/" is interpreted as an absolute path or as a path relative to the current directory. Otherwise, the set of search paths currently in effect for the runtime linker is used to locate the specific file. See NOTES.

Any dependencies recorded within the pathname object are also loaded as part of the dlopen() call. The dependencies are searched in the order they are loaded to locate any additional dependencies. The search continues until all dependencies of pathname are loaded.

If the value of pathname is 0, then dlopen() provides a handle for the global symbol object. The global symbol object provides access to the symbols from an ordered set of objects consisting of the original program image file and any dependencies loaded at program startup, and any objects loaded using dlopen(). Because the set of objects loaded using dlopen() can change during actor execution, the set identified by handle can also change dynamically.

An object may be opened multiple times by dlopen(). As long as the object has not been removed from memory using dlclose(), the same handle is returned each time dlopen() is called. A counter is maintained internally to record the number of consecutive openings.

The mode parameter describes how dlopen() operates on pathname with regard to relocation processing and scope of symbols from pathname and its dependencies. When an object is brought into the address space of an actor, it may contain references to symbols for which addresses are not known until the object is loaded. These types of references must be relocated before the symbols can be accessed. The mode parameter governs how these relocations are processed. The following modes are supported:

RTLD_NOW: Performs all necessary relocations when the object is first loaded.
RTLD_GLOBAL: Makes the object's global symbols available for relocation processing of any other object.
RTLD_LOCAL: Makes the object's global symbols available only for relocation processing of other objects in the same group.

The program image file and any objects loaded at program startup use the RTLD_GLOBAL mode. By default, all objects accessed using dlopen() use RTLD_LOCAL mode. Any local object may depend on more than one group. Any object using RTLD_LOCAL mode referenced as a dependency of an object using RTLD_GLOBAL mode is promoted to RTLD_GLOBAL, and RTLD_LOCAL is ignored. Any object loaded by dlopen() that requires relocation of global symbols can reference the symbols in any RTLD_GLOBAL object, including, at least, the program image file, any objects loaded at program startup, the object itself and any dependencies that the object references. However, the following bitwise-OR values affecting the scope of symbol availability can also be added to the mode parameter:

RTLD_GROUP: Makes only symbols from the associated group available for relocation. The group is the object and all dependencies of the object. A group must be completely self-contained. All dependencies between members of the group must satisfy the relocation requirements of each object in the group.
RTLD_WORLD: Makes only symbols from RTLD_GLOBAL objects available for relocation.

The default modes for dlopen() are RTLD_WORLD and RTLD_GROUP. Both modes are bitwise-ORed together if the object is required by different dependencies specifying different modes.

Note -

RTLD_LAZY (lazy-binding) and RTLD_PARENT are not supported.

The following modes provide additional functionality beyond relocation processing:

RTLD_NODELETE: Does not delete the specified object from the address space as part of dlclose(). The opening counter is still decremented, however.
RTLD_NOLOAD: Does not load the specified object as part of the dlopen() call, but a valid handle is returned if the object already exists in the actor address space. Additional modes can be specified and are bitwise-ORed with the current mode of the object and its dependencies. RTLD_NOLOAD provides a means of querying the presence, or promoting the modes, of an existing dependency. Note that RTLD_NOLOAD does not prevent the opening counter of the object from being incremented. Therefore, using it on an existing object requires an additional dlclose() to effectively remove the object from memory.

RETURN VALUES

If the specified pathname cannot be found, cannot be opened for reading, is not a relocatable object, or if an error occurs while loading pathname or while relocating its symbolic references, dlopen() returns NULL.

ATTRIBUTES

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

ATTRIBUTE TYPE	ATTRIBUTE VALUE
Interface Stability	Evolving

NOTES

If other objects are were link-editied with pathname when pathname was built -- that is, if pathname has dependencies on other objects -- those objects are automatically loaded by dlopen(). Unless pathname contains "/", the directory search path used to find both pathname and the objects it depends upon may be set using either the environment variable LD_LIBRARY_PATH, which is analyzed at actor startup, or the runpath setting within the object calling dlopen(). Objects whose names resolve to the same absolute or relative pathname may be opened any number of times using dlopen(). However, the object referenced is loaded only once into the address space of the current actor.

ChorusOS 5.0 Last Revised December 2001