]>
Commit | Line | Data |
---|---|---|
affaa041 MK |
1 | .\" Copyright (C) 2015 Michael Kerrisk <mtk.manpages@gmail.com> |
2 | .\" and Copyright (C) 2008 Petr Baudis <pasky@suse.cz> (dladdr caveat) | |
3 | .\" | |
5fbde956 | 4 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
affaa041 | 5 | .\" |
7bd6328f | 6 | .TH DLADDR 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual" |
affaa041 MK |
7 | .SH NAME |
8 | dladdr, dladdr1 \- translate address to symbolic information | |
eda8a717 AC |
9 | .SH LIBRARY |
10 | Dynamic linking library | |
11 | .RI ( libdl ", " \-ldl ) | |
affaa041 MK |
12 | .SH SYNOPSIS |
13 | .nf | |
14 | .B #define _GNU_SOURCE | |
15 | .B #include <dlfcn.h> | |
dbfe9c70 | 16 | .PP |
bacf0915 AC |
17 | .BI "int dladdr(const void *" addr ", Dl_info *" info ); |
18 | .BI "int dladdr1(const void *" addr ", Dl_info *" info ", void **" extra_info , | |
19 | .BI " int " flags ); | |
affaa041 MK |
20 | .fi |
21 | .SH DESCRIPTION | |
22 | The function | |
23 | .BR dladdr () | |
24 | determines whether the address specified in | |
1ae6b2c7 | 25 | .I addr |
affaa041 MK |
26 | is located in one of the shared objects loaded by the calling application. |
27 | If it is, then | |
28 | .BR dladdr () | |
29 | returns information about the shared object and symbol that overlaps | |
30 | .IR addr . | |
31 | This information is returned in a | |
32 | .I Dl_info | |
33 | structure: | |
51f5698d | 34 | .PP |
affaa041 | 35 | .in +4n |
b8302363 | 36 | .EX |
affaa041 MK |
37 | typedef struct { |
38 | const char *dli_fname; /* Pathname of shared object that | |
39 | contains address */ | |
40 | void *dli_fbase; /* Base address at which shared | |
41 | object is loaded */ | |
42 | const char *dli_sname; /* Name of symbol whose definition | |
43 | overlaps \fIaddr\fP */ | |
44 | void *dli_saddr; /* Exact address of symbol named | |
45 | in \fIdli_sname\fP */ | |
46 | } Dl_info; | |
b8302363 | 47 | .EE |
affaa041 MK |
48 | .in |
49 | .PP | |
50 | If no symbol matching | |
51 | .I addr | |
52 | could be found, then | |
53 | .I dli_sname | |
54 | and | |
55 | .I dli_saddr | |
56 | are set to NULL. | |
847e0d88 | 57 | .PP |
affaa041 MK |
58 | The function |
59 | .BR dladdr1 () | |
60 | is like | |
61 | .BR dladdr (), | |
62 | but returns additional information via the argument | |
63 | .IR extra_info . | |
64 | The information returned depends on the value specified in | |
65 | .IR flags , | |
66 | which can have one of the following values: | |
67 | .TP | |
68 | .B RTLD_DL_LINKMAP | |
10b22cd9 | 69 | Obtain a pointer to the link map for the matched file. |
affaa041 | 70 | The |
1ae6b2c7 | 71 | .I extra_info |
affaa041 MK |
72 | argument points to a pointer to a |
73 | .I link_map | |
74 | structure (i.e., | |
1ae6b2c7 | 75 | .IR "struct link_map\~**" ), |
affaa041 MK |
76 | defined in |
77 | .I <link.h> | |
78 | as: | |
847e0d88 | 79 | .IP |
affaa041 | 80 | .in +4n |
b8302363 | 81 | .EX |
affaa041 MK |
82 | struct link_map { |
83 | ElfW(Addr) l_addr; /* Difference between the | |
84 | address in the ELF file and | |
85 | the address in memory */ | |
86 | char *l_name; /* Absolute pathname where | |
87 | object was found */ | |
88 | ElfW(Dyn) *l_ld; /* Dynamic section of the | |
89 | shared object */ | |
90 | struct link_map *l_next, *l_prev; | |
91 | /* Chain of loaded objects */ | |
92 | ||
93 | /* Plus additional fields private to the | |
94 | implementation */ | |
95 | }; | |
b8302363 | 96 | .EE |
affaa041 MK |
97 | .in |
98 | .TP | |
99 | .B RTLD_DL_SYMENT | |
10b22cd9 | 100 | Obtain a pointer to the ELF symbol table entry of the matching symbol. |
affaa041 | 101 | The |
1ae6b2c7 | 102 | .I extra_info |
affaa041 MK |
103 | argument is a pointer to a symbol pointer: |
104 | .IR "const ElfW(Sym) **" . | |
105 | The | |
106 | .IR ElfW () | |
107 | macro definition turns its argument into the name of an ELF data | |
108 | type suitable for the hardware architecture. | |
109 | For example, on a 64-bit platform, | |
110 | .I ElfW(Sym) | |
111 | yields the data type name | |
112 | .IR Elf64_Sym , | |
113 | which is defined in | |
1ae6b2c7 | 114 | .I <elf.h> |
affaa041 | 115 | as: |
847e0d88 | 116 | .IP |
affaa041 | 117 | .in +4n |
b8302363 | 118 | .EX |
30ea59e7 | 119 | typedef struct { |
affaa041 MK |
120 | Elf64_Word st_name; /* Symbol name */ |
121 | unsigned char st_info; /* Symbol type and binding */ | |
122 | unsigned char st_other; /* Symbol visibility */ | |
123 | Elf64_Section st_shndx; /* Section index */ | |
124 | Elf64_Addr st_value; /* Symbol value */ | |
125 | Elf64_Xword st_size; /* Symbol size */ | |
126 | } Elf64_Sym; | |
b8302363 | 127 | .EE |
affaa041 | 128 | .in |
847e0d88 | 129 | .IP |
affaa041 MK |
130 | The |
131 | .I st_name | |
132 | field is an index into the string table. | |
847e0d88 | 133 | .IP |
affaa041 MK |
134 | The |
135 | .I st_info | |
136 | field encodes the symbol's type and binding. | |
137 | The type can be extracted using the macro | |
1ae6b2c7 | 138 | .B ELF64_ST_TYPE(st_info) |
affaa041 | 139 | (or |
1ae6b2c7 | 140 | .B ELF32_ST_TYPE() |
affaa041 MK |
141 | on 32-bit platforms), which yields one of the following values: |
142 | .in +4n | |
143 | .TS | |
144 | lb lb | |
145 | lb l. | |
146 | Value Description | |
147 | STT_NOTYPE Symbol type is unspecified | |
148 | STT_OBJECT Symbol is a data object | |
149 | STT_FUNC Symbol is a code object | |
150 | STT_SECTION Symbol associated with a section | |
3c650501 | 151 | STT_FILE Symbol's name is filename |
affaa041 MK |
152 | STT_COMMON Symbol is a common data object |
153 | STT_TLS Symbol is thread-local data object | |
154 | STT_GNU_IFUNC Symbol is indirect code object | |
155 | .TE | |
156 | .in | |
157 | .IP | |
158 | The symbol binding can be extracted from the | |
159 | .I st_info | |
160 | field using the macro | |
1ae6b2c7 | 161 | .B ELF64_ST_BIND(st_info) |
affaa041 | 162 | (or |
1ae6b2c7 | 163 | .B ELF32_ST_BIND() |
affaa041 | 164 | on 32-bit platforms), which yields one of the following values: |
affaa041 MK |
165 | .in +4n |
166 | .TS | |
167 | lb lb | |
168 | lb l. | |
169 | Value Description | |
170 | STB_LOCAL Local symbol | |
171 | STB_GLOBAL Global symbol | |
172 | STB_WEAK Weak symbol | |
173 | STB_GNU_UNIQUE Unique symbol | |
174 | .TE | |
175 | .in | |
176 | .IP | |
177 | The | |
178 | .I st_other | |
179 | field contains the symbol's visibility, which can be extracted using the macro | |
1ae6b2c7 | 180 | .B ELF64_ST_VISIBILITY(st_info) |
affaa041 | 181 | (or |
1ae6b2c7 | 182 | .B ELF32_ST_VISIBILITY() |
affaa041 MK |
183 | on 32-bit platforms), which yields one of the following values: |
184 | .in +4n | |
185 | .TS | |
186 | lb lb | |
187 | lb l. | |
188 | Value Description | |
189 | STV_DEFAULT Default symbol visibility rules | |
190 | STV_INTERNAL Processor-specific hidden class | |
191 | STV_HIDDEN Symbol unavailable in other modules | |
192 | STV_PROTECTED Not preemptible, not exported | |
193 | .TE | |
194 | .in | |
195 | .SH RETURN VALUE | |
196 | On success, these functions return a nonzero value. | |
197 | If the address specified in | |
198 | .I addr | |
199 | could be matched to a shared object, | |
200 | but not to a symbol in the shared object, then the | |
cd415e73 | 201 | .I info\->dli_sname |
affaa041 | 202 | and |
cd415e73 | 203 | .I info\->dli_saddr |
affaa041 | 204 | fields are set to NULL. |
847e0d88 | 205 | .PP |
affaa041 MK |
206 | If the address specified in |
207 | .I addr | |
208 | could not be matched to a shared object, then these functions return 0. | |
209 | In this case, an error message is | |
210 | .I not | |
211 | .\" According to the FreeBSD man page, dladdr1() does signal an | |
212 | .\" error via dlerror() for this case. | |
213 | available via | |
214 | .BR dlerror (3). | |
215 | .SH VERSIONS | |
216 | .BR dladdr () | |
217 | is present in glibc 2.0 and later. | |
218 | .BR dladdr1 () | |
219 | first appeared in glibc 2.3.3. | |
06c0008d ZL |
220 | .SH ATTRIBUTES |
221 | For an explanation of the terms used in this section, see | |
222 | .BR attributes (7). | |
c466875e MK |
223 | .ad l |
224 | .nh | |
06c0008d ZL |
225 | .TS |
226 | allbox; | |
c466875e | 227 | lbx lb lb |
06c0008d ZL |
228 | l l l. |
229 | Interface Attribute Value | |
230 | T{ | |
231 | .BR dladdr (), | |
232 | .BR dladdr1 () | |
233 | T} Thread safety MT-Safe | |
234 | .TE | |
c466875e MK |
235 | .hy |
236 | .ad | |
237 | .sp 1 | |
3113c7f3 | 238 | .SH STANDARDS |
affaa041 MK |
239 | These functions are nonstandard GNU extensions |
240 | that are also present on Solaris. | |
241 | .SH BUGS | |
242 | Sometimes, the function pointers you pass to | |
243 | .BR dladdr () | |
244 | may surprise you. | |
9ea5bc66 | 245 | On some architectures (notably i386 and x86-64), |
affaa041 MK |
246 | .I dli_fname |
247 | and | |
248 | .I dli_fbase | |
249 | may end up pointing back at the object from which you called | |
250 | .BR dladdr (), | |
251 | even if the function used as an argument should come from | |
252 | a dynamically linked library. | |
253 | .PP | |
254 | The problem is that the function pointer will still be resolved | |
255 | at compile time, but merely point to the | |
256 | .I plt | |
257 | (Procedure Linkage Table) | |
258 | section of the original object (which dispatches the call after | |
259 | asking the dynamic linker to resolve the symbol). | |
260 | To work around this, | |
261 | you can try to compile the code to be position-independent: | |
262 | then, the compiler cannot prepare the pointer | |
ce65f81e | 263 | at compile time any more and |
affaa041 MK |
264 | .BR gcc (1) |
265 | will generate code that just loads the final symbol address from the | |
266 | .I got | |
267 | (Global Offset Table) at run time before passing it to | |
268 | .BR dladdr (). | |
269 | .SH SEE ALSO | |
270 | .BR dl_iterate_phdr (3), | |
9987012c | 271 | .BR dlinfo (3), |
affaa041 | 272 | .BR dlopen (3), |
de7d051d | 273 | .BR dlsym (3), |
affaa041 | 274 | .BR ld.so (8) |