Standard C Library Functions dlopen(3C)
NAME
dlopen, dlmopen - gain access to an executable object file
SYNOPSIS
#include
#include
void * dlopen(const char *pathname, int mode);
void * dlmopen(Lmid_t lmid, const char *pathname, int mode);
DESCRIPTION
The dlopen() function makes an executable object file avail-
able to a running process. dlopen() returns to the process a
handle that the process can use on subsequent calls to dlsym(3C), dladdr(3C), dlinfo(3C), and dlclose(3C). 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.If the object file referenced by dlopen() is not already
loaded as part of the process, then the object file is added to the process address space. A handle for this object is created and returned to the caller. If the object file is already part of the process, a handle is also returned to the caller. Multiple references to the same object result inreturning the same handle. A reference count within the han-
dle maintains the number of callers. The dlclose() of a han-
dle results in decrementing the handles reference count.When the reference count reaches 0 the object file is a can-
didate for unloading. Any init section within an object is called once when the object is loaded. Any fini section within an object is called once when the object is unloaded.When dlopen() causes an object to be loaded, it also loads
any non-lazy dependencies that are recorded within the
object given by pathname. These dependencies are searched in the order in which the dependencies 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.SunOS 5.11 Last change: 17 May 2010 1
Standard C Library Functions dlopen(3C)
If the value of pathname is 0, dlopen() provides a handle on
a set of global symbol objects. These objects consist of theoriginal program image file, any dependencies loaded at pro-
gram 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 han-
dle can also change dynamically.The mode argument describes how dlopen() operates on path-
name with respect to the processing of reference reloca-
tions. 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, the object can contain references to symbols whose addresses are not known until the object isloaded. These references must be relocated before the sym-
bols can be accessed. References are categorized as eitherimmediate or lazy. Immediate references are typically refer-
ences to data items used by the object code. Immediatereferences include pointers to functions and calls to func-
tions made from position-dependent shared objects. Lazy
references are typically calls to global functions that aremade from position-independent shared objects.
Lazy references can also be identified as deferred. See the-z deferred option of ld(1). Deferred dependencies are only
loaded during process execution, when the first binding to a deferred reference is made. These references are unaffected by the mode.The mode argument governs when non-deferred references take
place. The mode argument can be one of the following values.RTLD_LAZY Only immediate symbol references are relocated
when the object is first loaded. Lazy refer-
ences are not relocated until a given function is called for the first time. This value formode should improve performance, since a pro-
cess might not require all lazy references inany given object. This behavior mimics the nor-
mal loading of dependencies during process ini-
tialization. See NOTES.RTLD_NOW All non-deferred relocations are performed when
the object is first loaded. This process might waste some processing if relocations areSunOS 5.11 Last change: 17 May 2010 2
Standard C Library Functions dlopen(3C)
performed for lazy references that are never used. However, this mode ensures that when anobject is loaded, all non-deferred symbols that
are referenced during execution are available.This behavior mimics the loading of dependen-
cies 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 that are available for relocation can be affected by mode. To specify the scope of visibilityfor symbols that are 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 avail-
able for the relocation processing of any other object. In addition, symbol lookupusing dlopen(0, mode) and an associated
dlsym() allows objects that are loaded withRTLD_GLOBAL to be searched.
RTLD_LOCAL The object's globals symbols are only avail-
able for the relocation processing of other objects that include the same group. The program image file and any objects loaded at programstartup have the mode RTLD_GLOBAL. The mode RTLD_LOCAL is
the default mode for any objects that are acquired with dlo-
pen(). A local object can be a dependency of more then onegroup. 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 anyRTLD_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:SunOS 5.11 Last change: 17 May 2010 3
Standard C Library Functions dlopen(3C)
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 mustbe completely self-contained. All dependency
relationships between the members of thegroup must be sufficient to satisfy the relo-
cation requirements of each object that defines the group.RTLD_PARENT The symbols of the object initiating the dlo-
pen() call are made available to the objectsobtained by dlopen(). This option is useful
when hierarchical dlopen() families are
created. Although the parent object can sup-
ply 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 requires additional modes, the
mode parameter can be the bitwise-inclusive OR of the
required modes together with the 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 aspart of the process address space. Addi-
tional modes can be specified as abitwise-inclusive OR with the present mode
of the object and its dependencies. TheRTLD_NOLOAD mode provides a means of query-
ing the presence or promoting the modes of an existing dependency.SunOS 5.11 Last change: 17 May 2010 4
Standard C Library Functions dlopen(3C)
The default use of a handle with dlsym() allows a symbol search to inspect all objects that are associated with thegroup of objects that are loaded from dlopen(). The mode
parameter can also be a bitwise-inclusive OR with the fol-
lowing 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 andwithout 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 LibrariesGuide 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 validLmid_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 that areopened on a new link-map list must express
all of their dependencies.RETURN VALUES
The dlopen() function returns NULL if pathname cannot be
found, cannot be opened for reading, or is not a sharedobject or a relocatable object. dlopen() 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().SunOS 5.11 Last change: 17 May 2010 5
Standard C Library Functions dlopen(3C)
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 availableonly to dynamically-linked processes. See the Linker and
Libraries Guide.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
| Standard | See standards(5). ||_____________________________|_____________________________|
SEE ALSO
ld(1), ld.so.1(1), dladdr(3C), dlclose(3C), dldump(3C),dlerror(3C), dlinfo(3C), dlsym(3C), attributes(5), stan-
dards(5) Linker and Libraries Guide NOTES If pathname has dependencies on other objects, these objectsare automatically loaded by dlopen(). The directory search
path used to find pathname and any dependencies can be affected by setting the environment variableLD_LIBRARY_PATH. Any LD_LIBRARY_PATH variable is analyzed
once at process startup. The search path can also be affected from a runpath setting within the object from whichthe call to dlopen() originates. These search rules will
only be applied to path names that do not contain an embed-
ded '/'. Objects whose names resolve to the same absolute path name or relative path name can be opened any number oftimes using dlopen(). However, the object that is 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 symbolicSunOS 5.11 Last change: 17 May 2010 6
Standard C Library Functions dlopen(3C)
link.When building objects to be loaded on a new link-map list,
some precautions need to be taken. In general, all dependen-
cies must be included when building an object. Also, include/usr/lib/libmapmalloc.so.1 before /lib/libc.so.1 when build-
ing an object.When an object is loaded on a new link-map list, the object
is isolated from the main running program. Certain globalresources are only usable from one link-map list. A few
examples are the sbrk() based malloc(), libthread(), and the signal vectors. Care must be taken not to use any of theseresources 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 sharedobjects can not be available to the runtime linker. The sym-
bol table created by ld for use by the runtime linker might contain only a subset of the symbols that are defined in the object. As part of loading a new object, initialization code withinthe object is called before the dlopen() returns. This ini-
tialization is user code, and as such, can produce errorsthat 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 oferror. See the LD_DEBUG environment variable of ld.so.1(1).
Loading relocatable objects is an expensive operation that requires converting the relocatable object into a shared object memory image. This capability may be useful in a debugging environment, but is not recommended for production software.SunOS 5.11 Last change: 17 May 2010 7