1dlopen(3C)               Standard C Library Functions               dlopen(3C)
2
3
4

NAME

6       dlopen, dlmopen - gain access to an executable object file
7

SYNOPSIS

9       #include <dlfcn.h>
10       #include <link.h>
11
12       void * dlopen(const char *pathname, int mode);
13
14
15       void * dlmopen(Lmid_t lmid, const char *pathname, int mode);
16
17

DESCRIPTION

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
29
30       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
36
37       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
44
45       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
51
52       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
63       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
71
72       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
81
82
83       See the Linker and Libraries Guide for more  information  about  symbol
84       references.
85
86
87       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
92       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
98
99       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
103
104
105       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
112
113       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
121       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
129
130       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
138
139       RTLD_WORLD     Only symbols from RTLD_GLOBAL objects are made available
140                      for relocation.
141
142
143
144       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
149
150       The  following modes provide additional capabilities outside of reloca‐
151       tion processing:
152
153       RTLD_NODELETE    The specified object is tagged to prevent its deletion
154                        from the address space as part of a dlclose().
155
156
157       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
166
167
168       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
173       RTLD_FIRST    Use  of  this  handle  with dlsym(), restricts the symbol
174                     search to the first object associated with the handle.
175
176
177
178       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
182
183       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
188
189       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
193       LM_ID_BASE     Load the object on the applications link-map list.
194
195
196       LM_ID_LDSO     Load  the  object on the dynamic linkers (ld.so.1) link-
197                      map list.
198
199
200       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
204

RETURN VALUES

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

USAGE

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

ATTRIBUTES

220       See attributes(5) for descriptions of the following attributes:
221
222
223
224
225       ┌─────────────────────────────┬─────────────────────────────┐
226       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
227       ├─────────────────────────────┼─────────────────────────────┤
228       │Interface Stability          │Standard                     │
229       ├─────────────────────────────┼─────────────────────────────┤
230       │MT−Level                     │MT−Safe                      │
231       └─────────────────────────────┴─────────────────────────────┘
232

SEE ALSO

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
237
238       Linker and Libraries Guide
239

NOTES

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
253
254       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
258
259       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
264
265       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
273
274       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
279
280       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
290
291       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.
295
296
297
298SunOS 5.11                        4 Feb 2005                        dlopen(3C)
Impressum