1DLOPEN(3) Linux Programmer's Manual DLOPEN(3)
2
6 dladdr, dlclose, dlerror, dlopen, dlsym, dlvsym - programming interface
7 to dynamic linking loader
8
10 #include <dlfcn.h>
11 void *dlopen(const char *filename, int flag);
13 char *dlerror(void);
15 void *dlsym(void *handle, const char *symbol);
17 int dlclose(void *handle);
19
21 The four functions dlopen(), dlsym(), dlclose(), dlerror() implement
22 the interface to the dynamic linking loader.
23 dlerror
25 The function dlerror() returns a human readable string describing the
26 most recent error that occurred from dlopen(), dlsym() or dlclose()
27 since the last call to dlerror(). It returns NULL if no errors have
28 occurred since initialization or since it was last called.
29 dlopen
31 The function dlopen() loads the dynamic library file named by the null-
32 terminated string filename and returns an opaque "handle" for the
33 dynamic library. If filename is NULL, then the returned handle is for
34 the main program. If filename contains a slash ("/"), then it is
35 interpreted as a (relative or absolute) pathname. Otherwise, the
36 dynamic linker searches for the library as follows (see ld.so(8) for
37 further details):
38 o (ELF only) If the executable file for the calling program con‐
40 tains a DT_RPATH tag, and does not contain a DT_RUNPATH tag,
41 then the directories listed in the DT_RPATH tag are searched.
42 o If the environment variable LD_LIBRARY_PATH is defined to con‐
44 tain a colon-separated list of directories, then these are
45 searched. (As a security measure this variable is ignored for
46 set-user-ID and set-group-ID programs.)
47 o (ELF only) If the executable file for the calling program con‐
49 tains a DT_RUNPATH tag, then the directories listed in that tag
50 are searched.
51 o The cache file /etc/ld.so.cache (maintained by ldconfig(8)) is
53 checked to see whether it contains an entry for filename.
54 o The directories /lib and /usr/lib are searched (in that order).
56 If the library has dependencies on other shared libraries, then these
58 are also automatically loaded by the dynamic linker using the same
59 rules. (This process may occur recursively, if those libraries in turn
60 have dependencies, and so on.)
61 One of the following two values must be included in flag:
63 RTLD_LAZY
65 Perform lazy binding. Only resolve symbols as the code that
66 references them is executed. If the symbol is never referenced,
67 then it is never resolved. (Lazy binding is only performed for
68 function references; references to variables are always immedi‐
69 ately bound when the library is loaded.)
70 RTLD_NOW
72 If this value is specified, or the environment variable
73 LD_BIND_NOW is set to a non-empty string, all undefined symbols
74 in the library are resolved before dlopen() returns. If this
75 cannot be done, an error is returned.
76 Zero of more of the following values may also be ORed in flag:
78 RTLD_GLOBAL
80 The symbols defined by this library will be made available for
81 symbol resolution of subsequently loaded libraries.
82 RTLD_LOCAL
84 This is the converse of RTLD_GLOBAL, and the default if neither
85 flag is specified. Symbols defined in this library are not made
86 available to resolve references in subsequently loaded
87 libraries.
88 RTLD_NODELETE (since glibc 2.2)
90 Do not unload the library during dlclose(). Consequently, the
91 library's static variables are not reinitialised if the library
92 is reloaded with dlopen() at a later time. This flag is not
93 specified in POSIX.1-2001.
94 RTLD_NOLOAD (since glibc 2.2)
96 Don't load the library. This can be used to test if the library
97 is already resident (dlopen() returns NULL if it is not, or the
98 library's handle if it is resident). This flag can also be used
99 to promote the flags on a library that is already loaded. For
100 example, a library that was previously loaded with RTLD_LOCAL
101 can be re-opened with RTLD_NOLOAD | RTLD_GLOBAL. This flag is
102 not specified in POSIX.1-2001.
103 RTLD_DEEPBIND (since glibc 2.3.4)
105 Place the lookup scope of the symbols in this library ahead of
106 the global scope. This means that a self-contained library will
107 use its own symbols in preference to global symbols with the
108 same name contained in libraries that have already been loaded.
109 This flag is not specified in POSIX.1-2001.
110 If filename is a NULL pointer, then the returned handle is for the main
112 program. When given to dlsym(), this handle causes a search for a sym‐
113 bol in the main program, followed by all shared libraries loaded at
114 program startup, and then all shared libraries loaded by dlopen() with
115 the flag RTLD_GLOBAL.
116 External references in the library are resolved using the libraries in
118 that library's dependency list and any other libraries previously
119 opened with the RTLD_GLOBAL flag. If the executable was linked with
120 the flag "-rdynamic" (or, synonymously, "--export-dynamic"), then the
121 global symbols in the executable will also be used to resolve refer‐
122 ences in a dynamically loaded library.
123 If the same library is loaded again with dlopen(), the same file handle
125 is returned. The dl library maintains reference counts for library han‐
126 dles, so a dynamic library is not deallocated until dlclose() has been
127 called on it as many times as dlopen() has succeeded on it. The _init
128 routine, if present, is only called once. But a subsequent call with
129 RTLD_NOW may force symbol resolution for a library earlier loaded with
130 RTLD_LAZY.
131 If dlopen() fails for any reason, it returns NULL.
133 dlsym
135 The function dlsym() takes a "handle" of a dynamic library returned by
136 dlopen() and the null-terminated symbol name, returning the address
137 where that symbol is loaded into memory. If the symbol is not found,
138 in the specified library or any of the libraries that were automati‐
139 cally loaded by dlopen() when that library was loaded, dlsym() returns
140 NULL. (The search performed by dlsym() is breadth first through the
141 dependency tree of these libraries.) Since the value of the symbol
142 could actually be NULL (so that a NULL return from dlsym() need not
143 indicate an error), the correct way to test for an error is to call
144 dlerror() to clear any old error conditions, then call dlsym(), and
145 then call dlerror() again, saving its return value into a variable, and
146 check whether this saved value is not NULL.
147 There are two special pseudo-handles, RTLD_DEFAULT and RTLD_NEXT. The
149 former will find the first occurrence of the desired symbol using the
150 default library search order. The latter will find the next occurrence
151 of a function in the search order after the current library. This
152 allows one to provide a wrapper around a function in another shared
153 library.
154 dlclose
156 The function dlclose() decrements the reference count on the dynamic
157 library handle handle. If the reference count drops to zero and no
158 other loaded libraries use symbols in it, then the dynamic library is
159 unloaded.
160 The function dlclose() returns 0 on success, and non-zero on error.
162 The obsolete symbols _init and _fini
164 The linker recognizes special symbols _init and _fini. If a dynamic
165 library exports a routine named _init, then that code is executed after
166 the loading, before dlopen() returns. If the dynamic library exports a
167 routine named _fini, then that routine is called just before the
168 library is unloaded. In case you need to avoid linking against the
169 system startup files, this can be done by giving gcc the "-nostart‐
170 files" parameter on the command line.
171 Using these routines, or the gcc -nostartfiles or -nostdlib options, is
173 not recommended. Their use may result in undesired behavior, since the
174 constructor/destructor routines will not be executed (unless special
175 measures are taken).
176 Instead, libraries should export routines using the __attribute__((con‐
178 structor)) and __attribute__((destructor)) function attributes. See
179 the gcc info pages for information on these. Constructor routines are
180 executed before dlopen() returns, and destructor routines are executed
181 before dlclose() returns.
182
184 Glibc adds two functions not described by POSIX, with prototypes
185 #define _GNU_SOURCE
187 #include <dlfcn.h>
188 int dladdr(void *addr, Dl_info *info);
190 void *dlvsym(void *handle, char *symbol, char *version);
192 The function dladdr() takes a function pointer and tries to resolve
194 name and file where it is located. Information is stored in the Dl_info
195 structure:
196 typedef struct {
198 const char *dli_fname;/* Filename of defining object */
199 void *dli_fbase; /* Load address of that object */
200 const char *dli_sname;/* Name of nearest lower symbol */
201 void *dli_saddr; /* Exact value of nearest symbol */
202 } Dl_info;
203 dladdr() returns 0 on error, and non-zero on success.
205 The function dlvsym() does the same as dlsym() but takes a version
207 string as an additional argument.
208
211 Load the math library, and print the cosine of 2.0:
212 #include <stdio.h>
214 #include <stdlib.h>
215 #include <dlfcn.h>
216 int main(int argc, char **argv) {
218 void *handle;
219 double (*cosine)(double);
220 char *error;
221 handle = dlopen ("libm.so", RTLD_LAZY);
223 if (!handle) {
224 fprintf (stderr, "%s\n", dlerror());
225 exit(1);
226 }
227 dlerror(); /* Clear any existing error */
229 *(void **) (&cosine) = dlsym(handle, "cos");
230 if ((error = dlerror()) != NULL) {
231 fprintf (stderr, "%s\n", error);
232 exit(1);
233 }
234 printf ("%f\n", (*cosine)(2.0));
236 dlclose(handle);
237 return 0;
238 }
239 If this program were in a file named "foo.c", you would build the pro‐
241 gram with the following command:
242 gcc -rdynamic -o foo foo.c -ldl
244 Libraries exporting _init() and _fini() will want to be compiled as
246 follows, using bar.c as the example name:
247 gcc -shared -nostartfiles -o bar bar.c
249
251 The symbols RTLD_DEFAULT and RTLD_NEXT are defined by <dlfcn.h> only
252 when _GNU_SOURCE was defined before including it.
253 Since glibc 2.2.3, atexit(3) can be used to register an exit handler
255 that is automatically called when a library is unloaded.
256
258 The dlopen interface standard comes from SunOS. That system also has
259 dladdr(), but not dlvsym().
260
262 POSIX.1-2001 describes dlclose(), dlerror(), dlopen(), and dlsym().
263
265 ld(1), ldd(1), dl_iterate_phdr(3), feature_test_macros(7) ld.so(8),
266 ldconfig(8), ld.so info pages, gcc info pages, ld info pages
267Linux 2003-11-17 DLOPEN(3)