Debian Codegraph @

upstream/debian-unstable/man3/dladdr.3

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