1dlopen(3C) Standard C Library Functions dlopen(3C)
2
6 dlopen, dlmopen - gain access to an executable object file
7
9 #include <dlfcn.h>
10 #include <link.h>
11 void * dlopen(const char *pathname, int mode);
13 void * dlmopen(Lmid_t lmid, const char *pathname, int mode);
16
19 The dlopen() function makes an executable object file available to a
20 running process. dlopen() returns to the process a handle that the
21 process can use on subsequent calls to dlsym(3C), dladdr(3C),
22 dlinfo(3C), and dlclose(3C). The value of this handle should not be
23 interpreted in any way by the process. The pathname argument is the
24 path name of the object to be opened. A path name containing an embed‐
25 ded '/' is interpreted as an absolute path or relative to the current
26 directory. Otherwise, the set of search paths currently in effect by
27 the runtime linker are used to locate the specified file. See NOTES.
28 The dlopen() function also loads any dependencies recorded within path‐
31 name. These dependencies are searched in the order in which the depen‐
32 dencies were loaded to locate any additional dependencies. This process
33 continues until all the dependencies of pathname are loaded. This
34 dependency tree is referred to as a group.
35 If the value of pathname is 0, dlopen() provides a handle on a set of
38 global symbol objects. These objects consist of the original program
39 image file, any dependencies loaded at program startup, and any objects
40 loaded using dlopen() with the RTLD_GLOBAL flag. Because the latter set
41 of objects can change during process execution, the set identified by
42 handle can also change dynamically.
43 The mode argument describes how dlopen() operates on pathname with
46 respect to the processing of reference relocations. The mode also
47 affects the scope of visibility of the symbols provided by pathname and
48 its dependencies. This visibility can affect how the resulting handle
49 is used.
50 When an object is loaded, the object can contain references to symbols
53 whose addresses are not known until the object is loaded. These refer‐
54 ences must be relocated before the symbols can be accessed. References
55 are categorized as either immediate or lazy. Immediate references are
56 typically references to data items used by the object code. Immediate
57 references include pointers to functions and calls to functions made
58 from position-dependent shared objects. Lazy references are typically
59 calls to global functions that are made from position-independent
60 shared objects. The mode argument governs when these references take
61 place. The mode argument can be one of the following values:
62 RTLD_LAZY Only immediate symbol references are relocated when the
64 object is first loaded. Lazy references are not relocated
65 until a given function is called for the first time. This
66 value for mode should improve performance, since a process
67 might not require all lazy references in any given object.
68 This behavior mimics the normal loading of dependencies
69 during process initialization. See NOTES.
70 RTLD_NOW All necessary relocations are performed when the object is
73 first loaded. This process might waste some processing if
74 relocations are performed for lazy references that are
75 never used. However, this mode ensures that when an object
76 is loaded, all symbols referenced during execution are
77 available. This behavior mimics the loading of dependen‐
78 cies when the environment variable LD_BIND_NOW is in
79 effect.
80 See the Linker and Libraries Guide for more information about symbol
84 references.
85 The visibility of symbols that are available for relocation can be
88 affected by mode. To specify the scope of visibility for symbols that
89 are loaded with a dlopen() call, mode should be a bitwise-inclusive OR
90 with one of the following values:
91 RTLD_GLOBAL The object's global symbols are made available for the
93 relocation processing of any other object. In addition,
94 symbol lookup using dlopen(0, mode) and an associated
95 dlsym() allows objects that are loaded with RTLD_GLOBAL
96 to be searched.
97 RTLD_LOCAL The object's globals symbols are only available for the
100 relocation processing of other objects that include the
101 same group.
102 The program image file and any objects loaded at program startup have
106 the mode RTLD_GLOBAL. The mode RTLD_LOCAL is the default mode for any
107 objects that are acquired with dlopen(). A local object can be a depen‐
108 dency of more then one group. Any object of mode RTLD_LOCAL that is
109 referenced as a dependency of an object of mode RTLD_GLOBAL is promoted
110 to RTLD_GLOBAL. In other words, the RTLD_LOCAL mode is ignored.
111 Any object loaded by dlopen() that requires relocations against global
114 symbols can reference the symbols in any RTLD_GLOBAL object. Objects of
115 this mode are at least the program image file and any objects loaded at
116 program startup. A loaded object can also reference symbols from
117 itself, and from any dependencies the object references. However, the
118 mode parameter can also be a bitwise-inclusive OR with one of the fol‐
119 lowing values to affect the scope of symbol availability:
120 RTLD_GROUP Only symbols from the associated group are made avail‐
122 able for relocation. A group is established from the
123 defined object and all the dependencies of that object.
124 A group must be completely self-contained. All depen‐
125 dency relationships between the members of the group
126 must be sufficient to satisfy the relocation require‐
127 ments of each object that defines the group.
128 RTLD_PARENT The symbols of the object initiating the dlopen() call
131 are made available to the objects obtained by dlopen().
132 This option is useful when hierarchical dlopen() fami‐
133 lies are created. Although the parent object can supply
134 symbols for the relocation of this object, the parent
135 object is not available to dlsym() through the returned
136 handle.
137 RTLD_WORLD Only symbols from RTLD_GLOBAL objects are made available
140 for relocation.
141 The default modes for dlopen() are both RTLD_WORLD and RTLD_GROUP. If
145 an object is requires additional modes, the mode parameter can be the
146 bitwise-inclusive OR of the required modes together with the default
147 modes.
148 The following modes provide additional capabilities outside of reloca‐
151 tion processing:
152 RTLD_NODELETE The specified object is tagged to prevent its deletion
154 from the address space as part of a dlclose().
155 RTLD_NOLOAD The specified object is not loaded as part of the
158 dlopen(). However, a valid handle is returned if the
159 object already exists as part of the process address
160 space. Additional modes can be specified as a bitwise-
161 inclusive OR with the present mode of the object and
162 its dependencies. The RTLD_NOLOAD mode provides a
163 means of querying the presence or promoting the modes
164 of an existing dependency.
165 The default use of a handle with dlsym() allows a symbol search to
169 inspect all objects that are associated with the group of objects that
170 are loaded from dlopen(). The mode parameter can also be a bitwise-
171 inclusive OR with the following value to restrict this symbol search:
172 RTLD_FIRST Use of this handle with dlsym(), restricts the symbol
174 search to the first object associated with the handle.
175 An object can be accessed from a process both with and without
179 RTLD_FIRST. Although the object will only be loaded once, two different
180 handles are created to provide for the different dlsym() requirements.
181 The dlmopen() function is identical to dlopen(), except that an identi‐
184 fying link-map ID (lmid) is provided. This link-map ID informs the
185 dynamic linking facilities upon which link-map list to load the object.
186 See the Linker and Libraries Guide for details about link-maps.
187 The lmid passed to dlmopen() identifies the link-map list on which the
190 object is loaded. This parameter can be any valid Lmid_t returned by
191 dlinfo() or one of the following special values:
192 LM_ID_BASE Load the object on the applications link-map list.
194 LM_ID_LDSO Load the object on the dynamic linkers (ld.so.1) link-
197 map list.
198 LM_ID_NEWLM Cause the object to create a new link-map list as part
201 of loading. Objects that are opened on a new link-map
202 list must express all of their dependencies.
203
206 The dlopen() function returns NULL if pathname cannot be found, cannot
207 be opened for reading, or is not a shared object or a relocatable
208 object. dlopen() also returns NULL if an error occurs during the
209 process of loading pathname or relocating its symbolic references. See
210 NOTES. Additional diagnostic information is available through dler‐
211 ror().
212
214 The dlopen() and dlmopen() functions are members of a family of func‐
215 tions that give the user direct access to the dynamic linking facili‐
216 ties. This family of functions is available only to dynamically-linked
217 processes. See the Linker and Libraries Guide.
218
220 See attributes(5) for descriptions of the following attributes:
221 ┌─────────────────────────────┬─────────────────────────────┐
226 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
227 ├─────────────────────────────┼─────────────────────────────┤
228 │Interface Stability │Standard │
229 ├─────────────────────────────┼─────────────────────────────┤
230 │MT−Level │MT−Safe │
231 └─────────────────────────────┴─────────────────────────────┘
232
234 ld(1), ld.so.1(1), dladdr(3C), dlclose(3C), dldump(3C), dlerror(3C),
235 dlinfo(3C), dlsym(3C), attributes(5), standards(5)
236 Linker and Libraries Guide
239
241 If pathname has dependencies on other objects, these objects are auto‐
242 matically loaded by dlopen(). The directory search path used to find
243 pathname and any dependencies can be affected by setting the environ‐
244 ment variable LD_LIBRARY_PATH. Any LD_LIBRARY_PATH variable is analyzed
245 once at process startup. The search path can also be affected from a
246 runpath setting within the object from which the call to dlopen() orig‐
247 inates. These search rules will only be applied to path names that do
248 not contain an embedded '/'. Objects whose names resolve to the same
249 absolute path name or relative path name can be opened any number of
250 times using dlopen(). However, the object that is referenced will only
251 be loaded once into the address space of the current process.
252 When loading shared objects, the application should open a specific
255 version of the shared object. Do not rely on the version of the shared
256 object pointed to by the symbolic link.
257 When building objects to be loaded on a new link-map list, some precau‐
260 tions need to be taken. In general, all dependencies must be included
261 when building an object. Also, include /usr/lib/libmapmalloc.so.1
262 before /lib/libc.so.1 when building an object.
263 When an object is loaded on a new link-map list, the object is isolated
266 from the main running program. Certain global resources are only usable
267 from one link-map list. A few examples are the sbrk() based malloc(),
268 libthread(), and the signal vectors. Care must be taken not to use any
269 of these resources other than from the primary link-map list. These
270 issues are discussed in further detail in the Linker and Libraries
271 Guide.
272 Some symbols defined in dynamic executables or shared objects can not
275 be available to the runtime linker. The symbol table created by ld for
276 use by the runtime linker might contain only a subset of the symbols
277 that are defined in the object.
278 As part of loading a new object, initialization code within the object
281 is called before the dlopen() returns. This initialization is user
282 code, and as such, can produce errors that can not be caught by
283 dlopen(). For example, an object loaded using RTLD_LAZY that attempts
284 to call a function that can not be located results in process termina‐
285 tion. Erroneous programming practices within the initialization code
286 can also result in process termination. The runtime linkers debugging
287 facility can offer help identifying these types of error. See the
288 LD_DEBUG environment variable of ld.so.1(1).
289 Loading relocatable objects is an expensive operation that requires
292 converting the relocatable object into a shared object memory image.
293 This capability may be useful in a debugging environment, but is not
294 recommended for production software.
295SunOS 5.11 4 Feb 2005 dlopen(3C)