summaryrefslogtreecommitdiffstats
path: root/man3/dlopen.3
blob: 3774e9ebc7a9fd02c191eb0cd6326a333c872cf2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
'\" t
.\" Copyright 1995 Yggdrasil Computing, Incorporated.
.\" written by Adam J. Richter (adam@yggdrasil.com),
.\" with typesetting help from Daniel Quinlan (quinlan@yggdrasil.com).
.\" and Copyright 2003, 2015 Michael Kerrisk <mtk.manpages@gmail.com>
.\"
.\" SPDX-License-Identifier: GPL-2.0-or-later
.\"
.\" Modified by David A. Wheeler <dwheeler@dwheeler.com> 2000-11-28.
.\" Applied patch by Terran Melconian, aeb, 2001-12-14.
.\" Modified by Hacksaw <hacksaw@hacksaw.org> 2003-03-13.
.\" Modified by Matt Domsch, 2003-04-09: _init and _fini obsolete
.\" Modified by Michael Kerrisk <mtk.manpages@gmail.com> 2003-05-16.
.\" Modified by Walter Harms: dladdr, dlvsym
.\" Modified by Petr Baudis <pasky@suse.cz>, 2008-12-04: dladdr caveat
.\"
.TH dlopen 3 2023-07-20 "Linux man-pages 6.05.01"
.SH NAME
dlclose, dlopen, dlmopen \-
open and close a shared object
.SH LIBRARY
Dynamic linking library
.RI ( libdl ", " \-ldl )
.SH SYNOPSIS
.nf
.B #include <dlfcn.h>
.PP
.BI "void *dlopen(const char *" filename ", int " flags );
.BI "int dlclose(void *" handle );
.PP
.B #define _GNU_SOURCE
.br
.B #include <dlfcn.h>
.PP
.BI "void *dlmopen(Lmid_t " lmid ", const char *" filename ", int " flags );
.fi
.SH DESCRIPTION
.SS dlopen()
The function
.BR dlopen ()
loads the dynamic shared object (shared library)
file named by the null-terminated
string
.I filename
and returns an opaque "handle" for the loaded object.
This handle is employed with other functions in the dlopen API, such as
.BR dlsym (3),
.BR dladdr (3),
.BR dlinfo (3),
and
.BR dlclose ().
.PP
If
.I filename
.\" FIXME On Solaris, when handle is NULL, we seem to get back
.\" a handle for (something like) the root of the namespace.
.\" The point here is that if we do a dlmopen(LM_ID_NEWLM), then
.\" the filename==NULL case returns a different handle than
.\" in the initial namespace. But, on glibc, the same handle is
.\" returned. This is probably a bug in glibc.
.\"
is NULL, then the returned handle is for the main program.
If
.I filename
contains a slash ("/"), then it is interpreted as a (relative
or absolute) pathname.
Otherwise, the dynamic linker searches for the object as follows
(see
.BR ld.so (8)
for further details):
.IP \[bu] 3
(ELF only) If the calling object
(i.e., the shared library or executable from which
.BR dlopen ()
is called)
contains a DT_RPATH tag, and does not contain a DT_RUNPATH tag,
then the directories listed in the DT_RPATH tag are searched.
.IP \[bu]
If, at the time that the program was started, the environment variable
.B LD_LIBRARY_PATH
was defined to contain a colon-separated list of directories,
then these are searched.
(As a security measure, this variable is ignored for set-user-ID and
set-group-ID programs.)
.IP \[bu]
(ELF only) If the calling object
contains a DT_RUNPATH tag, then the directories listed in that tag
are searched.
.IP \[bu]
The cache file
.I /etc/ld.so.cache
(maintained by
.BR ldconfig (8))
is checked to see whether it contains an entry for
.IR filename .
.IP \[bu]
The directories
.I /lib
and
.I /usr/lib
are searched (in that order).
.PP
If the object specified by
.I filename
has dependencies on other shared objects,
then these are also automatically loaded by the dynamic linker
using the same rules.
(This process may occur recursively,
if those objects in turn have dependencies, and so on.)
.PP
One of the following two values must be included in
.IR flags :
.TP
.B RTLD_LAZY
Perform lazy binding.
Resolve symbols only as the code that references them is executed.
If the symbol is never referenced, then it is never resolved.
(Lazy binding is performed only for function references;
references to variables are always immediately bound when
the shared object is loaded.)
Since glibc 2.1.1,
.\" commit 12b5b6b7f78ea111e89bbf638294a5413c791072
this flag is overridden by the effect of the
.B LD_BIND_NOW
environment variable.
.TP
.B RTLD_NOW
If this value is specified, or the environment variable
.B LD_BIND_NOW
is set to a nonempty string,
all undefined symbols in the shared object are resolved before
.BR dlopen ()
returns.
If this cannot be done, an error is returned.
.PP
Zero or more of the following values may also be ORed in
.IR flags :
.TP
.B RTLD_GLOBAL
The symbols defined by this shared object will be
made available for symbol resolution of subsequently loaded shared objects.
.TP
.B RTLD_LOCAL
This is the converse of
.BR RTLD_GLOBAL ,
and the default if neither flag is specified.
Symbols defined in this shared object are not made available to resolve
references in subsequently loaded shared objects.
.TP
.BR RTLD_NODELETE " (since glibc 2.2)"
Do not unload the shared object during
.BR dlclose ().
Consequently, the object's static and global variables are not reinitialized
if the object is reloaded with
.BR dlopen ()
at a later time.
.TP
.BR RTLD_NOLOAD " (since glibc 2.2)"
Don't load the shared object.
This can be used to test if the object is already resident
.RB ( dlopen ()
returns NULL if it is not, or the object's handle if it is resident).
This flag can also be used to promote the flags on a shared object
that is already loaded.
For example, a shared object that was previously loaded with
.B RTLD_LOCAL
can be reopened with
.BR RTLD_NOLOAD\ |\ RTLD_GLOBAL .
.\"
.TP
.BR RTLD_DEEPBIND " (since glibc 2.3.4)"
.\" Inimitably described by UD in
.\" http://sources.redhat.com/ml/libc-hacker/2004-09/msg00083.html.
Place the lookup scope of the symbols in this
shared object ahead of the global scope.
This means that a self-contained object will use
its own symbols in preference to global symbols with the same name
contained in objects that have already been loaded.
.PP
If
.I filename
is NULL, then the returned handle is for the main program.
When given to
.BR dlsym (3),
this handle causes a search for a symbol in the main program,
followed by all shared objects loaded at program startup,
and then all shared objects loaded by
.BR dlopen ()
with the flag
.BR RTLD_GLOBAL .
.PP
Symbol references in the shared object are resolved using (in order):
symbols in the link map of objects loaded for the main program and its
dependencies;
symbols in shared objects (and their dependencies)
that were previously opened with
.BR dlopen ()
using the
.B RTLD_GLOBAL
flag;
and definitions in the shared object itself
(and any dependencies that were loaded for that object).
.PP
Any global symbols in the executable that were placed into
its dynamic symbol table by
.BR ld (1)
can also be used to resolve references in a dynamically loaded shared object.
Symbols may be placed in the dynamic symbol table
either because the executable was linked with the flag "\-rdynamic"
(or, synonymously, "\-\-export\-dynamic"), which causes all of
the executable's global symbols to be placed in the dynamic symbol table,
or because
.BR ld (1)
noted a dependency on a symbol in another object during static linking.
.PP
If the same shared object is opened again with
.BR dlopen (),
the same object handle is returned.
The dynamic linker maintains reference
counts for object handles, so a dynamically loaded shared object is not
deallocated until
.BR dlclose ()
has been called on it as many times as
.BR dlopen ()
has succeeded on it.
Constructors (see below) are called only when the object is actually loaded
into memory (i.e., when the reference count increases to 1).
.PP
A subsequent
.BR dlopen ()
call that loads the same shared object with
.B RTLD_NOW
may force symbol resolution for a shared object earlier loaded with
.BR RTLD_LAZY .
Similarly, an object that was previously opened with
.B RTLD_LOCAL
can be promoted to
.B RTLD_GLOBAL
in a subsequent
.BR dlopen ().
.PP
If
.BR dlopen ()
fails for any reason, it returns NULL.
.\"
.SS dlmopen()
This function performs the same task as
.BR dlopen ()\[em]the
.I filename
and
.I flags
arguments, as well as the return value, are the same,
except for the differences noted below.
.PP
The
.BR dlmopen ()
function differs from
.BR dlopen ()
primarily in that it accepts an additional argument,
.IR lmid ,
that specifies the link-map list (also referred to as a
.IR namespace )
in which the shared object should be loaded.
(By comparison,
.BR dlopen ()
adds the dynamically loaded shared object to the same namespace as
the shared object from which the
.BR dlopen ()
call is made.)
The
.I Lmid_t
type is an opaque handle that refers to a namespace.
.PP
The
.I lmid
argument is either the ID of an existing namespace
.\" FIXME: Is using dlinfo() RTLD_DI_LMID the right technique?
(which can be obtained using the
.BR dlinfo (3)
.B RTLD_DI_LMID
request) or one of the following special values:
.TP
.B LM_ID_BASE
Load the shared object in the initial namespace
(i.e., the application's namespace).
.TP
.B LM_ID_NEWLM
Create a new namespace and load the shared object in that namespace.
The object must have been correctly linked
to reference all of the other shared objects that it requires,
since the new namespace is initially empty.
.PP
If
.I filename
is NULL, then the only permitted value for
.I lmid
is
.BR LM_ID_BASE .
.SS dlclose()
The function
.BR dlclose ()
decrements the reference count on the
dynamically loaded shared object referred to by
.IR handle .
.PP
If the object's reference count drops to zero
and no symbols in this object are required by other objects,
then the object is unloaded
after first calling any destructors defined for the object.
(Symbols in this object might be required in another object
because this object was opened with the
.B RTLD_GLOBAL
flag and one of its symbols satisfied a relocation in another object.)
.PP
All shared objects that were automatically loaded when
.BR dlopen ()
was invoked on the object referred to by
.I handle
are recursively closed in the same manner.
.PP
A successful return from
.BR dlclose ()
does not guarantee that the symbols associated with
.I handle
are removed from the caller's address space.
In addition to references resulting from explicit
.BR dlopen ()
calls, a shared object may have been implicitly loaded
(and reference counted) because of dependencies in other shared objects.
Only when all references have been released can the shared object
be removed from the address space.
.SH RETURN VALUE
On success,
.BR dlopen ()
and
.BR dlmopen ()
return a non-NULL handle for the loaded object.
On error
(file could not be found, was not readable, had the wrong format,
or caused errors during loading),
these functions return NULL.
.PP
On success,
.BR dlclose ()
returns 0; on error, it returns a nonzero value.
.PP
Errors from these functions can be diagnosed using
.BR dlerror (3).
.SH ATTRIBUTES
For an explanation of the terms used in this section, see
.BR attributes (7).
.TS
allbox;
lbx lb lb
l l l.
Interface	Attribute	Value
T{
.na
.nh
.BR dlopen (),
.BR dlmopen (),
.BR dlclose ()
T}	Thread safety	MT-Safe
.TE
.sp 1
.SH STANDARDS
.TP
.BR dlopen ()
.TQ
.BR dlclose ()
POSIX.1-2008.
.TP
.BR dlmopen ()
.TQ
.B RTLD_NOLOAD
.TQ
.B RTLD_NODELETE
GNU.
.TP
.B RTLD_DEEPBIND
Solaris.
.SH HISTORY
.TP
.BR dlopen ()
.TQ
.BR dlclose ()
glibc 2.0.
POSIX.1-2001.
.TP
.BR dlmopen ()
glibc 2.3.4.
.SH NOTES
.SS dlmopen() and namespaces
A link-map list defines an isolated namespace for the
resolution of symbols by the dynamic linker.
Within a namespace,
dependent shared objects are implicitly loaded according to the usual rules,
and symbol references are likewise resolved according to the usual rules,
but such resolution is confined to the definitions provided by the
objects that have been (explicitly and implicitly) loaded into the namespace.
.PP
The
.BR dlmopen ()
function permits object-load isolation\[em]the ability
to load a shared object in a new namespace without
exposing the rest of the application to the symbols
made available by the new object.
Note that the use of the
.B RTLD_LOCAL
flag is not sufficient for this purpose,
since it prevents a shared object's symbols from being available to
.I any
other shared object.
In some cases,
we may want to make the symbols provided by a dynamically
loaded shared object available to (a subset of) other shared objects
without exposing those symbols to the entire application.
This can be achieved by using a separate namespace and the
.B RTLD_GLOBAL
flag.
.PP
The
.BR dlmopen ()
function also can be used to provide better isolation than the
.B RTLD_LOCAL
flag.
In particular, shared objects loaded with
.B RTLD_LOCAL
may be promoted to
.B RTLD_GLOBAL
if they are dependencies of another shared object loaded with
.BR RTLD_GLOBAL .
Thus,
.B RTLD_LOCAL
is insufficient to isolate a loaded shared object except in the (uncommon)
case where one has explicit control over all shared object dependencies.
.PP
Possible uses of
.BR dlmopen ()
are plugins where the author of the plugin-loading framework
can't trust the plugin authors and does not wish
any undefined symbols from the plugin framework to be resolved to plugin
symbols.
Another use is to load the same object more than once.
Without the use of
.BR dlmopen (),
this would require the creation of distinct copies of the shared object file.
Using
.BR dlmopen (),
this can be achieved by loading the same shared object file into
different namespaces.
.PP
The glibc implementation supports a maximum of
.\" DL_NNS
16 namespaces.
.\"
.SS Initialization and finalization functions
Shared objects may export functions using the
.B __attribute__((constructor))
and
.B __attribute__((destructor))
function attributes.
Constructor functions are executed before
.BR dlopen ()
returns, and destructor functions are executed before
.BR dlclose ()
returns.
A shared object may export multiple constructors and destructors,
and priorities can be associated with each function
to determine the order in which they are executed.
See the
.B gcc
info pages (under "Function attributes")
.\" info gcc "C Extensions" "Function attributes"
for further information.
.PP
An older method of (partially) achieving the same result is via the use of
two special symbols recognized by the linker:
.B _init
and
.BR _fini .
If a dynamically loaded shared object exports a routine named
.BR _init (),
then that code is executed after loading a shared object, before
.BR dlopen ()
returns.
If the shared object exports a routine named
.BR _fini (),
then that routine is called just before the object is unloaded.
In this case, one must avoid linking against the system startup files,
which contain default versions of these files;
this can be done by using the
.BR gcc (1)
.I \-nostartfiles
command-line option.
.PP
Use of
.B _init
and
.B _fini
is now deprecated in favor of the aforementioned
constructors and destructors,
which among other advantages,
permit multiple initialization and finalization functions to be defined.
.\"
.\" Using these routines, or the gcc
.\" .B \-nostartfiles
.\" or
.\" .B \-nostdlib
.\" options, is not recommended.
.\" Their use may result in undesired behavior,
.\" since the constructor/destructor routines will not be executed
.\" (unless special measures are taken).
.\" .\" void _init(void) __attribute__((constructor));
.\" .\" void _fini(void) __attribute__((destructor));
.\"
.PP
Since glibc 2.2.3,
.BR atexit (3)
can be used to register an exit handler that is automatically
called when a shared object is unloaded.
.SS History
These functions are part of the dlopen API, derived from SunOS.
.SH BUGS
As at glibc 2.24, specifying the
.B RTLD_GLOBAL
flag when calling
.BR dlmopen ()
.\" dlerror(): "invalid mode"
generates an error.
Furthermore, specifying
.B RTLD_GLOBAL
when calling
.BR dlopen ()
results in a program crash
.RB ( SIGSEGV )
.\" https://sourceware.org/bugzilla/show_bug.cgi?id=18684
if the call is made from any object loaded in a
namespace other than the initial namespace.
.SH EXAMPLES
The program below loads the (glibc) math library,
looks up the address of the
.BR cos (3)
function, and prints the cosine of 2.0.
The following is an example of building and running the program:
.PP
.in +4n
.EX
$ \fBcc dlopen_demo.c \-ldl\fP
$ \fB./a.out\fP
\-0.416147
.EE
.in
.SS Program source
\&
.\" SRC BEGIN (dlopen.c)
.EX
#include <dlfcn.h>
#include <stdio.h>
#include <stdlib.h>
\&
#include <gnu/lib\-names.h>  /* Defines LIBM_SO (which will be a
                               string such as "libm.so.6") */
int
main(void)
{
    void *handle;
    double (*cosine)(double);
    char *error;
\&
    handle = dlopen(LIBM_SO, RTLD_LAZY);
    if (!handle) {
        fprintf(stderr, "%s\en", dlerror());
        exit(EXIT_FAILURE);
    }
\&
    dlerror();    /* Clear any existing error */
\&
    cosine = (double (*)(double)) dlsym(handle, "cos");
\&
    /* According to the ISO C standard, casting between function
       pointers and \[aq]void *\[aq], as done above, produces undefined results.
       POSIX.1\-2001 and POSIX.1\-2008 accepted this state of affairs and
       proposed the following workaround:
\&
           *(void **) (&cosine) = dlsym(handle, "cos");
\&
       This (clumsy) cast conforms with the ISO C standard and will
       avoid any compiler warnings.
\&
       The 2013 Technical Corrigendum 1 to POSIX.1\-2008 improved matters
       by requiring that conforming implementations support casting
       \[aq]void *\[aq] to a function pointer.  Nevertheless, some compilers
       (e.g., gcc with the \[aq]\-pedantic\[aq] option) may complain about the
       cast used in this program. */
.\" http://pubs.opengroup.org/onlinepubs/009695399/functions/dlsym.html#tag_03_112_08
.\" http://pubs.opengroup.org/onlinepubs/9699919799/functions/dlsym.html#tag_16_96_07
.\" http://austingroupbugs.net/view.php?id=74
\&
    error = dlerror();
    if (error != NULL) {
        fprintf(stderr, "%s\en", error);
        exit(EXIT_FAILURE);
    }
\&
    printf("%f\en", (*cosine)(2.0));
    dlclose(handle);
    exit(EXIT_SUCCESS);
}
.EE
.\" SRC END
.SH SEE ALSO
.BR ld (1),
.BR ldd (1),
.BR pldd (1),
.BR dl_iterate_phdr (3),
.BR dladdr (3),
.BR dlerror (3),
.BR dlinfo (3),
.BR dlsym (3),
.BR rtld\-audit (7),
.BR ld.so (8),
.BR ldconfig (8)
.PP
gcc info pages, ld info pages