Penguin
Annotated edit history of dlopen(3) version 2, including all changes. View license author blame.
Rev Author # Line
1 perry 1 DLOPEN
2 !!!DLOPEN
3 NAME
4 SYNOPSIS
5 DESCRIPTION
6 RETURN VALUE
7 EXAMPLE
8 ACKNOWLEDGEMENTS
9 SEE ALSO
10 ----
11 !!NAME
12
13
14 dlclose, dlerror, dlopen, dlsym - Programming interface to dynamic linking loader.
15 !!SYNOPSIS
16
17
18 __#include __
19
20
21 __void *dlopen (const char *__''filename''__, int__
22 ''flag''__);
23 const char *dlerror(void);
24 void *dlsym(void *__''handle''__, char
25 *__''symbol''__);
26 int dlclose (void *__''handle''__);__
27
28
29 Special symbols: ___init__, ___fini__.
30 !!DESCRIPTION
31
32
33 __dlopen__ loads a dynamic library from the file named by
34 the null terminated string ''filename'' and returns an
35 opaque
36 ''filename'' is not an absolute path (i.e., it does not
37 begin with a
38 ''
39
40
41 A colon-separated list of directories in the user's
42 __LD_LIBRARY_PATH__ environment variable.
43
44
45 The list of libraries cached in
46 ''/etc/ld.so.cache''.
47
48
49 ''/usr/lib'', followed by ''/lib''.
50
51
52 If ''filename'' is a NULL pointer, then the returned
53 handle is for the main program.
54
55
56 External references in the library are resolved using the
57 libraries in that library's dependency list and any other
58 libraries previously opened with the __RTLD_GLOBAL__
59 flag. If the executable was linked with the flag
60 __
61
62
63 ''flag'' must be either __RTLD_LAZY__, meaning resolve
64 undefined symbols as code from the dynamic library is
65 executed, or __RTLD_NOW__, meaning resolve all undefined
66 symbols before __dlopen__ returns, and fail if this
67 cannot be done. Optionally, __RTLD_GLOBAL__ may be or'ed
68 with ''flag,'' in which case the external symbols defined
69 in the library will be made available to subsequently loaded
70 libraries.
71
72
73 If the library exports a routine named ___init__, then
74 that code is executed before dlopen returns. If the same
75 library is loaded twice with __dlopen()__, the same file
76 handle is returned. The dl library maintains link counts for
77 dynamic file handles, so a dynamic library is not
78 deallocated until __dlclose__ has been called on it as
79 many times as __dlopen__ has succeeded on
80 it.
81
82
83 If __dlopen__ fails for any reason, it returns NULL. A
84 human readable string describing the most recent error that
85 occurred from any of the dl routines (dlopen, dlsym or
86 dlclose) can be extracted with __dlerror()__.
87 __dlerror__ returns NULL if no errors have occurred since
88 initialization or since it was last called. (Calling
89 __dlerror()__ twice consecutively, will always result in
90 the second call returning NULL.)
91
92
93 __dlsym__ takes a
94 __dlsym__ returns NULL; however, the
95 correct way to test for an error from __dlsym__ is to
96 save the result of __dlerror__ into a variable, and then
97 check if saved value is not NULL. This is because the value
98 of the symbol could actually be NULL. It is also necessary
99 to save the results of __dlerror__ into a variable
100 because if __dlerror__ is called again, it will return
101 NULL.
102
103
104 __dlclose__ decrements the reference count on the dynamic
105 library handle ''handle''. If the reference count drops
106 to zero and no other loaded libraries use symbols in it,
107 then the dynamic library is unloaded. If the dynamic library
108 exports a routine named ___fini__, then that routine is
109 called just before the library is unloaded.
110 !!RETURN VALUE
111
112
113 __dlclose__ returns 0 on success, and non-zero on
114 error.
115 !!EXAMPLE
116
117
118 __Load the math library, and print the cosine of
119 2.0:__
120
121
122 #include
123
124
125 If this program were in a file named
126
127
128 gcc -rdynamic -o foo foo.c -ldl
129 !!ACKNOWLEDGEMENTS
130
131
132 The dlopen interface standard comes from Solaris. The Linux
133 dlopen implementation was primarily written by Eric
134 Youngdale with help from Mitch D'Souza, David Engel, Hongjiu
135 Lu, Andreas Schwab and others. The manual page was written
136 by Adam Richter.
137 !!SEE ALSO
138
139
2 perry 140 ld(1), ld.so(8), ldconfig(8),
1 perry 141 ldd(1), __ld.so.info__
142 ----
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.