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(Lmidt 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.
The dlopen() function also loads any dependencies recorded
within 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.
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 pro-
gram startup, and any objects loaded using dlopen() with the
RTLDGLOBAL 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.
SunOS 5.11 Last change: 4 Feb 2005 1
Standard C Library Functions dlopen(3C)
When an object is loaded, the object can contain references
to symbols whose addresses are not known until the object is
loaded. These references must be relocated before the sym-
bols can be accessed. References are categorized as either
immediate or lazy. Immediate references are typically refer-
ences to data items used by the object code. Immediate
references include pointers to functions and calls to func-
tions made from position-dependent shared objects. Lazy
references are typically calls to global functions that are
made from position-independent shared objects. The mode
argument governs when these references take place. The mode
argument can be one of the following values:
RTLDLAZY 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 for
mode should improve performance, since a pro-
cess might not require all lazy references in
any given object. This behavior mimics the nor-
mal loading of dependencies during process ini-
tialization. See NOTES.
RTLDNOW All necessary relocations are performed when
the object is first loaded. This process might
waste some processing if relocations are per-
formed for lazy references that are never used.
However, this mode ensures that when an object
is loaded, all symbols referenced during execu-
tion are available. This behavior mimics the
loading of dependencies when the environment
variable LDBINDNOW 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 visibility
for symbols that are loaded with a dlopen() call, mode
should be a bitwise-inclusive OR with one of the following
values:
RTLDGLOBAL The object's global symbols are made avail-
able for the relocation processing of any
other object. In addition, symbol lookup
using dlopen(0, mode) and an associated
dlsym() allows objects that are loaded with
RTLDGLOBAL to be searched.
SunOS 5.11 Last change: 4 Feb 2005 2
Standard C Library Functions dlopen(3C)
RTLDLOCAL 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 program
startup have the mode RTLDGLOBAL. The mode RTLDLOCAL is
the default mode for any objects that are acquired with dlo-
pen(). A local object can be a dependency of more then one
group. Any object of mode RTLDLOCAL that is referenced as a
dependency of an object of mode RTLDGLOBAL is promoted to
RTLDGLOBAL. In other words, the RTLDLOCAL mode is ignored.
Any object loaded by dlopen() that requires relocations
against global symbols can reference the symbols in any
RTLDGLOBAL 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:
RTLDGROUP 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 relo-
cation requirements of each object that
defines the group.
RTLDPARENT The symbols of the object initiating the dlo-
pen() call are made available to the objects
obtained 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.
RTLDWORLD Only symbols from RTLDGLOBAL objects are
made available for relocation.
SunOS 5.11 Last change: 4 Feb 2005 3
Standard C Library Functions dlopen(3C)
The default modes for dlopen() are both RTLDWORLD and
RTLDGROUP. 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:
RTLDNODELETE The specified object is tagged to prevent
its deletion from the address space as part
of a dlclose().
RTLDNOLOAD 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. Addi-
tional modes can be specified as a
bitwise-inclusive OR with the present mode
of the object and its dependencies. The
RTLDNOLOAD mode provides a means of query-
ing 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 that are associated with the
group 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:
RTLDFIRST 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 RTLDFIRST. 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.
SunOS 5.11 Last change: 4 Feb 2005 4
Standard C Library Functions dlopen(3C)
The lmid passed to dlmopen() identifies the link-map list on
which the object is loaded. This parameter can be any valid
Lmidt returned by dlinfo() or one of the following special
values:
LMIDBASE Load the object on the applications link-map
list.
LMIDLDSO Load the object on the dynamic linkers
(ld.so.1) link-map list.
LMIDNEWLM Cause the object to create a new link-map
list as part of loading. Objects that are
opened on a new link-map list must express
all of their dependencies.
RETURN VALUES
The dlopen() function returns NUL if pathname cannot be
found, cannot be opened for reading, or is not a shared
object or a relocatable object. dlopen() also returns NUL
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.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Standard
MT-Level MT-Safe
SEE ALSO
ld(1), ld.so.1(1), dladdr(3C), dlclose(3C), dldump(3C),
dlerror(3C), dlinfo(3C), dlsym(3C), attributes(5),
SunOS 5.11 Last change: 4 Feb 2005 5
Standard C Library Functions dlopen(3C)
standards(5)
Linker and Libraries Guide
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 can be
affected by setting the environment variable
LDLIBRARYPATH. Any LDLIBRARYPATH variable is analyzed
once at process startup. The search path can 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 embed-
ded '/'. Objects whose names resolve to the same absolute
path name or relative path name can be opened any number of
times 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 symbolic
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 global
resources 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 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 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.
SunOS 5.11 Last change: 4 Feb 2005 6
Standard C Library Functions dlopen(3C)
As part of loading a new object, initialization code within
the object is called before the dlopen() returns. This ini-
tialization is user code, and as such, can produce errors
that can not be caught by dlopen(). For example, an object
loaded using RTLDLAZY 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 LDEBUG 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: 4 Feb 2005 7
|
