termios.3: wfix
[man-pages.git] / man3 / dladdr.3
blobc95df4e49bbfc511af4ad8fcb711992e1995a0f3
1 .\" Copyright (C) 2015 Michael Kerrisk <mtk.manpages@gmail.com>
2 .\" and Copyright (C) 2008 Petr Baudis <pasky@suse.cz> (dladdr caveat)
3 .\"
4 .\" %%%LICENSE_START(VERBATIM)
5 .\" Permission is granted to make and distribute verbatim copies of this
6 .\" manual provided the copyright notice and this permission notice are
7 .\" preserved on all copies.
8 .\"
9 .\" Permission is granted to copy and distribute modified versions of this
10 .\" manual under the conditions for verbatim copying, provided that the
11 .\" entire resulting derived work is distributed under the terms of a
12 .\" permission notice identical to this one.
13 .\"
14 .\" Since the Linux kernel and libraries are constantly changing, this
15 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
16 .\" responsibility for errors or omissions, or for damages resulting from
17 .\" the use of the information contained herein.  The author(s) may not
18 .\" have taken the same level of care in the production of this manual,
19 .\" which is licensed free of charge, as they might when working
20 .\" professionally.
21 .\"
22 .\" Formatted or processed versions of this manual, if unaccompanied by
23 .\" the source, must acknowledge the copyright and authors of this work.
24 .\" %%%LICENSE_END
25 .\"
26 .TH DLADDR 3 2021-03-22 "Linux" "Linux Programmer's Manual"
27 .SH NAME
28 dladdr, dladdr1 \- translate address to symbolic information
29 .SH SYNOPSIS
30 .nf
31 .B #define _GNU_SOURCE
32 .B #include <dlfcn.h>
33 .PP
34 .BI "int dladdr(const void *" addr ", Dl_info *" info );
35 .BI "int dladdr1(const void *" addr ", Dl_info *" info ", void **" extra_info ,
36 .BI "            int " flags );
37 .PP
38 Link with \fI\-ldl\fP.
39 .fi
40 .SH DESCRIPTION
41 The function
42 .BR dladdr ()
43 determines whether the address specified in
44 .IR addr
45 is located in one of the shared objects loaded by the calling application.
46 If it is, then
47 .BR dladdr ()
48 returns information about the shared object and symbol that overlaps
49 .IR addr .
50 This information is returned in a
51 .I Dl_info
52 structure:
53 .PP
54 .in +4n
55 .EX
56 typedef struct {
57     const char *dli_fname;  /* Pathname of shared object that
58                                contains address */
59     void       *dli_fbase;  /* Base address at which shared
60                                object is loaded */
61     const char *dli_sname;  /* Name of symbol whose definition
62                                overlaps \fIaddr\fP */
63     void       *dli_saddr;  /* Exact address of symbol named
64                                in \fIdli_sname\fP */
65 } Dl_info;
66 .EE
67 .in
68 .PP
69 If no symbol matching
70 .I addr
71 could be found, then
72 .I dli_sname
73 and
74 .I dli_saddr
75 are set to NULL.
76 .PP
77 The function
78 .BR dladdr1 ()
79 is like
80 .BR dladdr (),
81 but returns additional information via the argument
82 .IR extra_info .
83 The information returned depends on the value specified in
84 .IR flags ,
85 which can have one of the following values:
86 .TP
87 .B RTLD_DL_LINKMAP
88 Obtain a pointer to the link map for the matched file.
89 The
90 .IR extra_info
91 argument points to a pointer to a
92 .I link_map
93 structure (i.e.,
94 .IR "struct link_map\ **" ),
95 defined in
96 .I <link.h>
97 as:
98 .IP
99 .in +4n
101 struct link_map {
102     ElfW(Addr) l_addr;  /* Difference between the
103                            address in the ELF file and
104                            the address in memory */
105     char      *l_name;  /* Absolute pathname where
106                            object was found */
107     ElfW(Dyn) *l_ld;    /* Dynamic section of the
108                            shared object */
109     struct link_map *l_next, *l_prev;
110                         /* Chain of loaded objects */
112     /* Plus additional fields private to the
113        implementation */
118 .B RTLD_DL_SYMENT
119 Obtain a pointer to the ELF symbol table entry of the matching symbol.
121 .IR extra_info
122 argument is a pointer to a symbol pointer:
123 .IR "const ElfW(Sym) **" .
125 .IR ElfW ()
126 macro definition turns its argument into the name of an ELF data
127 type suitable for the hardware architecture.
128 For example, on a 64-bit platform,
129 .I ElfW(Sym)
130 yields the data type name
131 .IR Elf64_Sym ,
132 which is defined in
133 .IR <elf.h>
136 .in +4n
138 typedef struct  {
139     Elf64_Word    st_name;     /* Symbol name */
140     unsigned char st_info;     /* Symbol type and binding */
141     unsigned char st_other;    /* Symbol visibility */
142     Elf64_Section st_shndx;    /* Section index */
143     Elf64_Addr    st_value;    /* Symbol value */
144     Elf64_Xword   st_size;     /* Symbol size */
145 } Elf64_Sym;
150 .I st_name
151 field is an index into the string table.
154 .I st_info
155 field encodes the symbol's type and binding.
156 The type can be extracted using the macro
157 .BR ELF64_ST_TYPE(st_info)
159 .BR ELF32_ST_TYPE()
160 on 32-bit platforms), which yields one of the following values:
161 .in +4n
163 lb lb
164 lb l.
165 Value   Description
166 STT_NOTYPE      Symbol type is unspecified
167 STT_OBJECT      Symbol is a data object
168 STT_FUNC        Symbol is a code object
169 STT_SECTION     Symbol associated with a section
170 STT_FILE        Symbol's name is filename
171 STT_COMMON      Symbol is a common data object
172 STT_TLS Symbol is thread-local data object
173 STT_GNU_IFUNC   Symbol is indirect code object
177 The symbol binding can be extracted from the
178 .I st_info
179 field using the macro
180 .BR ELF64_ST_BIND(st_info)
182 .BR ELF32_ST_BIND()
183 on 32-bit platforms), which yields one of the following values:
184 .in +4n
186 lb lb
187 lb l.
188 Value   Description
189 STB_LOCAL       Local symbol
190 STB_GLOBAL      Global symbol
191 STB_WEAK        Weak symbol
192 STB_GNU_UNIQUE  Unique symbol
197 .I st_other
198 field contains the symbol's visibility, which can be extracted using the macro
199 .BR ELF64_ST_VISIBILITY(st_info)
201 .BR ELF32_ST_VISIBILITY()
202 on 32-bit platforms), which yields one of the following values:
203 .in +4n
205 lb lb
206 lb l.
207 Value   Description
208 STV_DEFAULT     Default symbol visibility rules
209 STV_INTERNAL    Processor-specific hidden class
210 STV_HIDDEN      Symbol unavailable in other modules
211 STV_PROTECTED   Not preemptible, not exported
214 .SH RETURN VALUE
215 On success, these functions return a nonzero value.
216 If the address specified in
217 .I addr
218 could be matched to a shared object,
219 but not to a symbol in the shared object, then the
220 .I info\->dli_sname
222 .I info\->dli_saddr
223 fields are set to NULL.
225 If the address specified in
226 .I addr
227 could not be matched to a shared object, then these functions return 0.
228 In this case, an error message is
229 .I not
230 .\" According to the FreeBSD man page, dladdr1() does signal an
231 .\" error via dlerror() for this case.
232 available via
233 .BR dlerror (3).
234 .SH VERSIONS
235 .BR dladdr ()
236 is present in glibc 2.0 and later.
237 .BR dladdr1 ()
238 first appeared in glibc 2.3.3.
239 .SH ATTRIBUTES
240 For an explanation of the terms used in this section, see
241 .BR attributes (7).
242 .ad l
245 allbox;
246 lbx lb lb
247 l l l.
248 Interface       Attribute       Value
250 .BR dladdr (),
251 .BR dladdr1 ()
252 T}      Thread safety   MT-Safe
256 .sp 1
257 .SH CONFORMING TO
258 These functions are nonstandard GNU extensions
259 that are also present on Solaris.
260 .SH BUGS
261 Sometimes, the function pointers you pass to
262 .BR dladdr ()
263 may surprise you.
264 On some architectures (notably i386 and x86-64),
265 .I dli_fname
267 .I dli_fbase
268 may end up pointing back at the object from which you called
269 .BR dladdr (),
270 even if the function used as an argument should come from
271 a dynamically linked library.
273 The problem is that the function pointer will still be resolved
274 at compile time, but merely point to the
275 .I plt
276 (Procedure Linkage Table)
277 section of the original object (which dispatches the call after
278 asking the dynamic linker to resolve the symbol).
279 To work around this,
280 you can try to compile the code to be position-independent:
281 then, the compiler cannot prepare the pointer
282 at compile time any more and
283 .BR gcc (1)
284 will generate code that just loads the final symbol address from the
285 .I got
286 (Global Offset Table) at run time before passing it to
287 .BR dladdr ().
288 .SH SEE ALSO
289 .BR dl_iterate_phdr (3),
290 .BR dlinfo (3),
291 .BR dlopen (3),
292 .BR dlsym (3),
293 .BR ld.so (8)