]>
Commit | Line | Data |
---|---|---|
15e1b31b | 1 | .\" Copyright 1995 Yggdrasil Computing, Incorporated. |
616c2730 | 2 | .\" and Copyright 2003, 2015 Michael Kerrisk <mtk.manpages@gmail.com> |
15e1b31b MK |
3 | .\" |
4 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) | |
5 | .\" This is free documentation; you can redistribute it and/or | |
6 | .\" modify it under the terms of the GNU General Public License as | |
7 | .\" published by the Free Software Foundation; either version 2 of | |
8 | .\" the License, or (at your option) any later version. | |
9 | .\" | |
10 | .\" The GNU General Public License's references to "object code" | |
11 | .\" and "executables" are to be interpreted as the output of any | |
12 | .\" document formatting or typesetting system, including | |
13 | .\" intermediate and printed output. | |
14 | .\" | |
15 | .\" This manual is distributed in the hope that it will be useful, | |
16 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 | .\" GNU General Public License for more details. | |
19 | .\" | |
20 | .\" You should have received a copy of the GNU General Public | |
21 | .\" License along with this manual; if not, see | |
22 | .\" <http://www.gnu.org/licenses/>. | |
23 | .\" %%%LICENSE_END | |
24 | .\" | |
4b8c67d9 | 25 | .TH DLSYM 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
15e1b31b MK |
26 | .SH NAME |
27 | dlsym, dlvsym \- obtain address of a symbol in a shared object or executable | |
28 | .SH SYNOPSIS | |
29 | .B #include <dlfcn.h> | |
68e4db0a | 30 | .PP |
15e1b31b | 31 | .BI "void *dlsym(void *" handle ", const char *" symbol ); |
dbfe9c70 | 32 | .PP |
15e1b31b MK |
33 | .B #define _GNU_SOURCE |
34 | .br | |
35 | .B #include <dlfcn.h> | |
68e4db0a | 36 | .PP |
15e1b31b | 37 | .BI "void *dlvsym(void *" handle ", char *" symbol ", char *" version ); |
68e4db0a | 38 | .PP |
15e1b31b MK |
39 | Link with \fI\-ldl\fP. |
40 | .SH DESCRIPTION | |
41 | The function | |
42 | .BR dlsym () | |
43 | takes a "handle" of a dynamic loaded shared object returned by | |
44 | .BR dlopen (3) | |
45 | along with a null-terminated symbol name, | |
46 | and returns the address where that symbol is | |
47 | loaded into memory. | |
48 | If the symbol is not found, in the specified | |
49 | object or any of the shared objects that were automatically loaded by | |
50 | .BR dlopen (3) | |
51 | when that object was loaded, | |
52 | .BR dlsym () | |
53 | returns NULL. | |
54 | (The search performed by | |
55 | .BR dlsym () | |
56 | is breadth first through the dependency tree of these shared objects.) | |
847e0d88 | 57 | .PP |
15e1b31b MK |
58 | Since the value of the symbol could actually be NULL (so that a |
59 | NULL return from | |
60 | .BR dlsym () | |
61 | need not indicate an error), the correct way to test for an error | |
62 | is to call | |
63 | .BR dlerror (3) | |
64 | to clear any old error conditions, then call | |
65 | .BR dlsym (), | |
66 | and then call | |
67 | .BR dlerror (3) | |
68 | again, saving its return value into a variable, and check whether | |
69 | this saved value is not NULL. | |
70 | .PP | |
71 | There are two special pseudo-handles that may be specified in | |
72 | .IR handle : | |
73 | .TP | |
74 | .B RTLD_DEFAULT | |
75 | Find the first occurrence of the desired symbol | |
76 | using the default shared object search order. | |
77 | The search will include global symbols in the executable | |
78 | and its dependencies, | |
79 | as well as symbols in shared objects that were dynamically loaded with the | |
80 | .BR RTLD_GLOBAL | |
81 | flag. | |
82 | .TP | |
83 | .BR RTLD_NEXT | |
84 | Find the next occurrence of the desired symbol in the search order | |
85 | after the current object. | |
86 | This allows one to provide a wrapper | |
87 | around a function in another shared object, so that, for example, | |
88 | the definition of a function in a preloaded shared object | |
89 | (see | |
90 | .B LD_PRELOAD | |
91 | in | |
92 | .BR ld.so (8)) | |
93 | can find and invoke the "real" function provided in another shared object | |
94 | (or for that matter, the "next" definition of the function in cases | |
95 | where there are multiple layers of preloading). | |
f9ce70d2 MK |
96 | .PP |
97 | The | |
98 | .B _GNU_SOURCE | |
99 | feature test macro must be defined in order to obtain the | |
100 | definitions of | |
101 | .B RTLD_DEFAULT | |
102 | and | |
103 | .B RTLD_NEXT | |
104 | from | |
105 | .IR <dlfcn.h> . | |
847e0d88 | 106 | .PP |
4590829a | 107 | .PP |
15e1b31b MK |
108 | The function |
109 | .BR dlvsym () | |
110 | does the same as | |
111 | .BR dlsym () | |
112 | but takes a version string as an additional argument. | |
113 | .SH RETURN VALUE | |
114 | On success, | |
115 | these functions return the address associated with | |
116 | .IR symbol . | |
117 | On failure, they return NULL; | |
118 | the cause of the error can be diagnosed using | |
119 | .BR dlerror (3). | |
120 | .SH VERSIONS | |
121 | .BR dlsym () | |
122 | is present in glibc 2.0 and later. | |
123 | .BR dlvsym () | |
124 | first appeared in glibc 2.1. | |
39720f03 MK |
125 | .SH ATTRIBUTES |
126 | For an explanation of the terms used in this section, see | |
127 | .BR attributes (7). | |
128 | .TS | |
129 | allbox; | |
130 | lb lb lb | |
131 | l l l. | |
132 | Interface Attribute Value | |
133 | T{ | |
134 | .BR dlsym (), | |
135 | .BR dlvsym () | |
136 | T} Thread safety MT-Safe | |
137 | .TE | |
15e1b31b MK |
138 | .SH CONFORMING TO |
139 | POSIX.1-2001 describes | |
140 | .BR dlsym (). | |
141 | The | |
142 | .BR dlvsym () | |
143 | function is a GNU extension. | |
144 | .SH NOTES | |
145 | .SS History | |
146 | The | |
147 | .BR dlsym () | |
148 | function is part of the dlopen API, derived from SunOS. | |
149 | That system does not have | |
150 | .BR dlvsym (). | |
151 | .SH EXAMPLE | |
152 | See | |
153 | .BR dlopen (3). | |
154 | .SH SEE ALSO | |
155 | .BR dl_iterate_phdr (3), | |
156 | .BR dladdr (3), | |
936b64f6 | 157 | .BR dlerror (3), |
15e1b31b MK |
158 | .BR dlinfo (3), |
159 | .BR dlopen (3), | |
160 | .BR ld.so (8) |