svcadm(8)을 검색하려면 섹션에서 8 을 선택하고, 맨 페이지 이름에 svcadm을 입력하고 검색을 누른다.
dlopen(3c)
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 in‐
terpreted 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 direc‐
tory. 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 re‐
turned to the caller. Multiple references to the same object result in
returning the same handle. A reference count within the handle main‐
tains the number of callers. The dlclose() of a handle results in
decrementing the handles reference count. When the reference count
reaches 0 the object file is a candidate for unloading. Any init sec‐
tion within an object is called once when the object is loaded. Any
fini section within an object is called once when the object is un‐
loaded.
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 contin‐
ues 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 re‐
spect to the processing of reference relocations. The mode also affects
the scope of visibility of the symbols provided by pathname and its de‐
pendencies. 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 refer‐
ences 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.
Lazy references can also be identified as deferred. See the -z de‐
ferred 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 references are not relocated until a given func‐
tion is called for the first time. This value for mode should im‐
prove performance, since a process might not require all lazy ref‐
erences in any given object. This behavior mimics the normal load‐
ing of dependencies during process initialization. See NOTES.
RTLD_NOW
All non-deferred 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 non-deferred sym‐
bols that are referenced during execution are available. This be‐
havior mimics the loading of dependencies when the environment
variable LD_BIND_NOW is in effect.
See the Oracle Solaris 11.4 Linkers and Libraries Guide for more infor‐
mation about symbol references.
The visibility of symbols that are available for relocation can be af‐
fected 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 depen‐
dency 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 it‐
self, and from any dependencies the object references. However, the
mode parameter can also be a bitwise-inclusive OR with one of the fol‐
lowing values to affect the scope of symbol availability:
RTLD_GROUP
Only symbols from the associated group are made available for relo‐
cation. A group is established from the defined object and all the
dependencies of that object. A group must be completely self-con‐
tained. 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 use‐
ful 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 relo‐
cation.
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 reloca‐
tion processing:
RTLD_NODELETE
The specified object is tagged to prevent its deletion from the ad‐
dress space as part of a dlclose().
RTLD_NOLOAD
The specified object is not loaded as part of the dlopen(). How‐
ever, a valid handle is returned if the object already exists as
part of the process address space. Additional modes can be speci‐
fied 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 depen‐
dency.
The default use of a handle with dlsym() allows a symbol search to in‐
spect all objects that are associated with the group of objects that
are loaded from dlopen(). The mode parameter can also be a bitwise-in‐
clusive 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 identi‐
fying link-map ID (lmid) is provided. This link-map ID informs the dy‐
namic linking facilities upon which link-map list to load the object.
See the Oracle Solaris 11.4 Linkers 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 ob‐
ject. 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 func‐
tions that give the user direct access to the dynamic linking facili‐
ties. This family of functions is available only to dynamically-linked
processes. See the Oracle Solaris 11.4 Linkers and Libraries Guide.
ATTRIBUTES
See attributes(7) for descriptions of the following attributes:
tab() box; cw(2.75i) |cw(2.75i) lw(2.75i) |lw(2.75i) ATTRIBUTE TYPEAT‐
TRIBUTE VALUE _ Interface StabilityCommitted _ MT−LevelMT−Safe _ Stan‐
dardSee standards(7).
SEE ALSO
ld(1), ld.so.1(1), dladdr(3C), dlclose(3C), dldump(3C), dlerror(3C),
dlinfo(3C), dlsym(3C), attributes(7), standards(7)
Oracle Solaris 11.4 Linkers and Libraries Guide
NOTES
dlopen() provides a callable interface to the standard object loading
functionality provided by the runtime linker. If pathname has dependen‐
cies on other objects, these objects are automatically loaded by
dlopen() in the usual manner. See ld.so.1(1), and Directories Searched
by the Link-Editor in Oracle Solaris 11.4 Linkers and Libraries Guide.
o The directory search path used to find pathname and any de‐
pendencies can be affected by setting environment variables
such as LD_LIBRARY_PATH. Such environment variables are are
analyzed once at process startup.
o The search path can also be affected from a runpath setting
within the object from which the call to dlopen() origi‐
nates.
o As with any object load operation, dependencies of dependen‐
cies are also loaded. The search for such subdependencies is
carried out in the usual manner, using the runpath contained
in the objects that require them.
o These search rules will only be applied to path names that
do not contain an embedded '/'. If an embedded '/' is
present, the path is loaded as given.
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 precau‐
tions need to be taken. In general, all dependencies must be included
when building an object. Also, include /usr/lib/libmapmalloc.so.1 be‐
fore /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(),
thread APIs, and the signal vectors. Care must be taken not to use any
of these resources other than from the primary link-map list. These is‐
sues are discussed in further detail in the Oracle Solaris 11.4 Linkers
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 termina‐
tion. 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.
Oracle Solaris 11.4 21 February 2023 dlopen(3C)