DLOPEN(3C) Standard C Library Functions DLOPEN(3C)

NAME

dlopen, dlmopen - gain access to an executable object file

SYNOPSIS

#include <dlfcn.h>
#include <link.h>

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 available 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 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, the object 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 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:

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 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:

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 that are 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
include 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 that are acquired with dlopen(). A local object can be a
dependency of more than 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 defines the group.


RTLD_PARENT
The symbols of the object initiating the dlopen() 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 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 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 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 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 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 that are opened 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 shared object 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().

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(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE 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(7), standards(7)


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 LD_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 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 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 dependencies must be
included when building an object. Also, include
/usr/lib/libmapmalloc.so.1 before /lib/libc.so.1 when building 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 symbol 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 within the
object is called before the dlopen() returns. This initialization is
user code, and as such, can 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).


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.

May 16, 2020 DLOPEN(3C)