Debian Codegraph @

upstream/debian-trixie/man3/dladdr.3

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