1DLOPEN(3)                  Linux Programmer's Manual                 DLOPEN(3)
2
3
4

NAME

6       dlclose, dlopen, dlmopen - open and close a shared object
7

SYNOPSIS

9       #include <dlfcn.h>
10
11       void *dlopen(const char *filename, int flags);
12
13       int dlclose(void *handle);
14
15       #define _GNU_SOURCE
16       #include <dlfcn.h>
17
18       void *dlmopen (Lmid_t lmid, const char *filename, int flags);
19
20       Link with -ldl.
21

DESCRIPTION

23   dlopen()
24       The  function dlopen() loads the dynamic shared object (shared library)
25       file named by the null-terminated string filename and returns an opaque
26       "handle"  for  the  loaded  object.  This handle is employed with other
27       functions in the dlopen API, such as  dlsym(3),  dladdr(3),  dlinfo(3),
28       and dlclose().
29
30       If  filename is NULL, then the returned handle is for the main program.
31       If filename contains a slash ("/"), then it is interpreted as a  (rela‐
32       tive or absolute) pathname.  Otherwise, the dynamic linker searches for
33       the object as follows (see ld.so(8) for further details):
34
35       o   (ELF only) If the executable file for the calling program  contains
36           a  DT_RPATH  tag,  and  does not contain a DT_RUNPATH tag, then the
37           directories listed in the DT_RPATH tag are searched.
38
39       o   If, at the time that the program was started, the environment vari‐
40           able  LD_LIBRARY_PATH was defined to contain a colon-separated list
41           of directories, then these are searched.  (As a  security  measure,
42           this  variable  is  ignored  for  set-user-ID and set-group-ID pro‐
43           grams.)
44
45       o   (ELF only) If the executable file for the calling program  contains
46           a  DT_RUNPATH  tag,  then  the  directories  listed in that tag are
47           searched.
48
49       o   The cache file  /etc/ld.so.cache  (maintained  by  ldconfig(8))  is
50           checked to see whether it contains an entry for filename.
51
52       o   The directories /lib and /usr/lib are searched (in that order).
53
54       If  the  object  specified by filename has dependencies on other shared
55       objects, then these are also automatically loaded by the dynamic linker
56       using  the  same  rules.  (This process may occur recursively, if those
57       objects in turn have dependencies, and so on.)
58
59       One of the following two values must be included in flags:
60
61       RTLD_LAZY
62              Perform lazy binding.  Resolve symbols only  as  the  code  that
63              references them is executed.  If the symbol is never referenced,
64              then it is never resolved.  (Lazy binding is performed only  for
65              function  references; references to variables are always immedi‐
66              ately bound when the shared  object  is  loaded.)   Since  glibc
67              2.1.1,  this flag is overridden by the effect of the LD_BIND_NOW
68              environment variable.
69
70       RTLD_NOW
71              If  this  value  is  specified,  or  the  environment   variable
72              LD_BIND_NOW  is  set to a nonempty string, all undefined symbols
73              in the shared object are resolved before dlopen()  returns.   If
74              this cannot be done, an error is returned.
75
76       Zero or more of the following values may also be ORed in flags:
77
78       RTLD_GLOBAL
79              The symbols defined by this shared object will be made available
80              for symbol resolution of subsequently loaded shared objects.
81
82       RTLD_LOCAL
83              This is the converse of RTLD_GLOBAL, and the default if  neither
84              flag  is  specified.   Symbols defined in this shared object are
85              not made available to resolve references in subsequently  loaded
86              shared objects.
87
88       RTLD_NODELETE (since glibc 2.2)
89              Do not unload the shared object during dlclose().  Consequently,
90              the object's static and global variables are  not  reinitialized
91              if the object is reloaded with dlopen() at a later time.
92
93       RTLD_NOLOAD (since glibc 2.2)
94              Don't  load  the shared object.  This can be used to test if the
95              object is already resident (dlopen() returns NULL if it is  not,
96              or  the  object's handle if it is resident).  This flag can also
97              be used to promote the flags on a shared object that is  already
98              loaded.  For example, a shared object that was previously loaded
99              with RTLD_LOCAL can be reopened with RTLD_NOLOAD | RTLD_GLOBAL.
100
101       RTLD_DEEPBIND (since glibc 2.3.4)
102              Place the lookup scope of the  symbols  in  this  shared  object
103              ahead  of  the  global  scope.  This means that a self-contained
104              object will use its own symbols in preference to global  symbols
105              with  the  same name contained in objects that have already been
106              loaded.
107
108       If filename is NULL, then the returned handle is for the main  program.
109       When given to dlsym(3), this handle causes a search for a symbol in the
110       main program, followed by all shared objects loaded at program startup,
111       and   then  all  shared  objects  loaded  by  dlopen()  with  the  flag
112       RTLD_GLOBAL.
113
114       Symbol references in the shared object are resolved using  (in  order):
115       symbols  in the link map of objects loaded for the main program and its
116       dependencies; symbols in shared objects (and their  dependencies)  that
117       were  previously  opened  with dlopen() using the RTLD_GLOBAL flag; and
118       definitions in the shared object itself (and any dependencies that were
119       loaded for that object).
120
121       Any  global symbols in the executable that were placed into its dynamic
122       symbol table by ld(1) can also be  used  to  resolve  references  in  a
123       dynamically loaded shared object.  Symbols may be placed in the dynamic
124       symbol table either because the executable was  linked  with  the  flag
125       "-rdynamic" (or, synonymously, "--export-dynamic"), which causes all of
126       the executable's global symbols to be placed in the dynamic symbol  ta‐
127       ble,  or because ld(1) noted a dependency on a symbol in another object
128       during static linking.
129
130       If the same shared object is  opened  again  with  dlopen(),  the  same
131       object  handle  is  returned.   The  dynamic linker maintains reference
132       counts for object handles, so a dynamically loaded shared object is not
133       deallocated  until  dlclose()  has  been  called on it as many times as
134       dlopen() has succeeded on it.  Constructors (see below) are called only
135       when  the  object is actually loaded into memory (i.e., when the refer‐
136       ence count increases to 1).
137
138       A subsequent dlopen() call that  loads  the  same  shared  object  with
139       RTLD_NOW may force symbol resolution for a shared object earlier loaded
140       with RTLD_LAZY.  Similarly, an object that was previously  opened  with
141       RTLD_LOCAL can be promoted to RTLD_GLOBAL in a subsequent dlopen().
142
143       If dlopen() fails for any reason, it returns NULL.
144
145   dlmopen()
146       This function performs the same task as dlopen()—the filename and flags
147       arguments, as well as the return value, are the same,  except  for  the
148       differences noted below.
149
150       The  dlmopen()  function  differs  from  dlopen()  primarily in that it
151       accepts an additional argument, lmid, that specifies the link-map  list
152       (also  referred to as a namespace) in which the shared object should be
153       loaded.  (By comparison, dlopen() adds the  dynamically  loaded  shared
154       object  to  the  same  namespace  as  the  shared object from which the
155       dlopen() call is made.)  The Lmid_t  type  is  an  opaque  handle  that
156       refers to a namespace.
157
158       The  lmid argument is either the ID of an existing namespace (which can
159       be obtained using the dlinfo(3) RTLD_DI_LMID request)  or  one  of  the
160       following special values:
161
162       LM_ID_BASE
163              Load  the  shared  object  in  the  initial namespace (i.e., the
164              application's namespace).
165
166       LM_ID_NEWLM
167              Create a new namespace and load the shared object in that names‐
168              pace.   The  object must have been correctly linked to reference
169              all of the other shared objects that it requires, since the  new
170              namespace is initially empty.
171
172       If  filename  is  NULL,  then  the  only  permitted  value  for lmid is
173       LM_ID_BASE.
174
175   dlclose()
176       The function dlclose() decrements the reference count  on  the  dynami‐
177       cally loaded shared object referred to by handle.
178
179       If  the  object's  reference count drops to zero and no symbols in this
180       object are required by other objects, then the object is unloaded after
181       first calling any destructors defined for the object.  (Symbols in this
182       object might be required in another  object  because  this  object  was
183       opened  with  the  RTLD_GLOBAL  flag and one of its symbols satisfied a
184       relocation in another object.)
185
186       All shared objects that were automatically  loaded  when  dlopen()  was
187       invoked  on  the object referred to by handle are recursively closed in
188       the same manner.
189
190       A successful return from dlclose() does not guarantee that the  symbols
191       associated with handle are removed from the caller's address space.  In
192       addition to references resulting from explicit dlopen() calls, a shared
193       object  may have been implicitly loaded (and reference counted) because
194       of dependencies in other shared objects.  Only when all references have
195       been released can the shared object be removed from the address space.
196

RETURN VALUE

198       On  success,  dlopen()  and  dlmopen() return a non-NULL handle for the
199       loaded object.  On error (file could not be found,  was  not  readable,
200       had the wrong format, or caused errors during loading), these functions
201       return NULL.
202
203       On success, dlclose() returns 0; on error, it returns a nonzero value.
204
205       Errors from these functions can be diagnosed using dlerror(3).
206

VERSIONS

208       dlopen() and dlclose() are present in glibc 2.0 and  later.   dlmopen()
209       first appeared in glibc 2.3.4.
210

ATTRIBUTES

212       For   an   explanation   of   the  terms  used  in  this  section,  see
213       attributes(7).
214
215       ┌───────────────────────────────┬───────────────┬─────────┐
216Interface                      Attribute     Value   
217       ├───────────────────────────────┼───────────────┼─────────┤
218dlopen(), dlmopen(), dlclose() │ Thread safety │ MT-Safe │
219       └───────────────────────────────┴───────────────┴─────────┘

CONFORMING TO

221       POSIX.1-2001 describes dlclose() and dlopen().  The dlmopen()  function
222       is a GNU extension.
223
224       The  RTLD_NOLOAD, RTLD_NODELETE, and RTLD_DEEPBIND flags are GNU exten‐
225       sions; the first two of these flags are also present on Solaris.
226

NOTES

228   dlmopen() and namespaces
229       A link-map list defines an isolated namespace  for  the  resolution  of
230       symbols  by  the  dynamic linker.  Within a namespace, dependent shared
231       objects are implicitly loaded according to the usual rules, and  symbol
232       references are likewise resolved according to the usual rules, but such
233       resolution is confined to the definitions provided by the objects  that
234       have been (explicitly and implicitly) loaded into the namespace.
235
236       The  dlmopen()  function  permits  object-load isolation—the ability to
237       load a shared object in a new namespace without exposing  the  rest  of
238       the  application to the symbols made available by the new object.  Note
239       that the use of the RTLD_LOCAL flag is not sufficient for this purpose,
240       since it prevents a shared object's symbols from being available to any
241       other shared object.  In some cases, we may want to  make  the  symbols
242       provided  by  a dynamically loaded shared object available to (a subset
243       of) other shared objects without exposing those symbols to  the  entire
244       application.   This  can  be achieved by using a separate namespace and
245       the RTLD_GLOBAL flag.
246
247       The dlmopen() function also can be used  to  provide  better  isolation
248       than  the  RTLD_LOCAL  flag.  In particular, shared objects loaded with
249       RTLD_LOCAL may be promoted to RTLD_GLOBAL if they are  dependencies  of
250       another  shared  object  loaded  with RTLD_GLOBAL.  Thus, RTLD_LOCAL is
251       insufficient to isolate a loaded shared object except in the (uncommon)
252       case  where  one  has explicit control over all shared object dependen‐
253       cies.
254
255       Possible uses of dlmopen() are plugins where the author of the  plugin-
256       loading  framework can't trust the plugin authors and does not wish any
257       undefined symbols from the plugin framework to be  resolved  to  plugin
258       symbols.  Another use is to load the same object more than once.  With‐
259       out the use of dlmopen(), this would require the creation  of  distinct
260       copies  of  the  shared  object  file.   Using  dlmopen(),  this can be
261       achieved by loading the same shared object file into  different  names‐
262       paces.
263
264       The glibc implementation supports a maximum of 16 namespaces.
265
266   Initialization and finalization functions
267       Shared  objects may export functions using the __attribute__((construc‐
268       tor)) and __attribute__((destructor)) function attributes.  Constructor
269       functions  are  executed  before dlopen() returns, and destructor func‐
270       tions are executed before  dlclose()  returns.   A  shared  object  may
271       export  multiple  constructors  and  destructors, and priorities can be
272       associated with each function to determine the order in which they  are
273       executed.   See  the  gcc  info pages (under "Function attributes") for
274       further information.
275
276       An older method of (partially) achieving the same result is via the use
277       of two special symbols recognized by the linker: _init and _fini.  If a
278       dynamically loaded shared object exports a routine named _init(),  then
279       that  code  is  executed after loading a shared object, before dlopen()
280       returns.  If the shared object exports a routine  named  _fini(),  then
281       that  routine  is  called  just before the object is unloaded.  In this
282       case, one must avoid linking against the system  startup  files,  which
283       contain  default versions of these files; this can be done by using the
284       gcc(1) -nostartfiles command-line option.
285
286       Use of _init and _fini is now deprecated in favor of the aforementioned
287       constructors and destructors, which among other advantages, permit mul‐
288       tiple initialization and finalization functions to be defined.
289
290       Since glibc 2.2.3, atexit(3) can be used to register  an  exit  handler
291       that is automatically called when a shared object is unloaded.
292
293   History
294       These functions are part of the dlopen API, derived from SunOS.
295

BUGS

297       As  at  glibc  2.24,  specifying  the  RTLD_GLOBAL  flag  when  calling
298       dlmopen() generates an error.  Furthermore, specifying RTLD_GLOBAL when
299       calling  dlopen()  results  in a program crash (SIGSEGV) if the call is
300       made from any object loaded in  a  namespace  other  than  the  initial
301       namespace.
302

EXAMPLES

304       The  program below loads the (glibc) math library, looks up the address
305       of the cos(3) function, and prints the cosine of 2.0.  The following is
306       an example of building and running the program:
307
308           $ cc dlopen_demo.c -ldl
309           $ ./a.out
310           -0.416147
311
312   Program source
313
314       #include <stdio.h>
315       #include <stdlib.h>
316       #include <dlfcn.h>
317       #include <gnu/lib-names.h>  /* Defines LIBM_SO (which will be a
318                                      string such as "libm.so.6") */
319       int
320       main(void)
321       {
322           void *handle;
323           double (*cosine)(double);
324           char *error;
325
326           handle = dlopen(LIBM_SO, RTLD_LAZY);
327           if (!handle) {
328               fprintf(stderr, "%s\n", dlerror());
329               exit(EXIT_FAILURE);
330           }
331
332           dlerror();    /* Clear any existing error */
333
334           cosine = (double (*)(double)) dlsym(handle, "cos");
335
336           /* According to the ISO C standard, casting between function
337              pointers and 'void *', as done above, produces undefined results.
338              POSIX.1-2001 and POSIX.1-2008 accepted this state of affairs and
339              proposed the following workaround:
340
341                  *(void **) (&cosine) = dlsym(handle, "cos");
342
343              This (clumsy) cast conforms with the ISO C standard and will
344              avoid any compiler warnings.
345
346              The 2013 Technical Corrigendum 1 to POSIX.1-2008 improved matters
347              by requiring that conforming implementations support casting
348              'void *' to a function pointer.  Nevertheless, some compilers
349              (e.g., gcc with the '-pedantic' option) may complain about the
350              cast used in this program. */
351
352           error = dlerror();
353           if (error != NULL) {
354               fprintf(stderr, "%s\n", error);
355               exit(EXIT_FAILURE);
356           }
357
358           printf("%f\n", (*cosine)(2.0));
359           dlclose(handle);
360           exit(EXIT_SUCCESS);
361       }
362

SEE ALSO

364       ld(1),  ldd(1),  pldd(1),  dl_iterate_phdr(3),  dladdr(3),  dlerror(3),
365       dlinfo(3), dlsym(3), rtld-audit(7), ld.so(8), ldconfig(8)
366
367       gcc info pages, ld info pages
368

COLOPHON

370       This page is part of release 5.07 of the Linux  man-pages  project.   A
371       description  of  the project, information about reporting bugs, and the
372       latest    version    of    this    page,    can     be     found     at
373       https://www.kernel.org/doc/man-pages/.
374
375
376
377Linux                             2020-06-09                         DLOPEN(3)
Impressum