]>
Commit | Line | Data |
---|---|---|
c11b1abf | 1 | .\" Copyright (c) 2003 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 2 | .\" |
93015253 | 3 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
4 | .\" Permission is granted to make and distribute verbatim copies of this |
5 | .\" manual provided the copyright notice and this permission notice are | |
6 | .\" preserved on all copies. | |
7 | .\" | |
8 | .\" Permission is granted to copy and distribute modified versions of this | |
9 | .\" manual under the conditions for verbatim copying, provided that the | |
10 | .\" entire resulting derived work is distributed under the terms of a | |
11 | .\" permission notice identical to this one | |
12 | .\" | |
13 | .\" Since the Linux kernel and libraries are constantly changing, this | |
14 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
15 | .\" responsibility for errors or omissions, or for damages resulting from | |
10d76543 MK |
16 | .\" the use of the information contained herein. The author(s) may not |
17 | .\" have taken the same level of care in the production of this manual, | |
18 | .\" which is licensed free of charge, as they might when working | |
19 | .\" professionally. | |
fea681da MK |
20 | .\" |
21 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
22 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 23 | .\" %%%LICENSE_END |
fea681da | 24 | .\" |
97986708 | 25 | .TH DL_ITERATE_PHDR 3 2016-03-15 "GNU" "Linux Programmer's Manual" |
fea681da MK |
26 | .SH NAME |
27 | dl_iterate_phdr \- walk through list of shared objects | |
28 | .SH SYNOPSIS | |
29 | .nf | |
b80f966b | 30 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
fea681da MK |
31 | .B #include <link.h> |
32 | ||
c9942389 MK |
33 | .BI "int dl_iterate_phdr(" |
34 | .BI " int (*" callback ") (struct dl_phdr_info *" info , | |
fa92a07b RV |
35 | .BI " size_t " size ", void *" data ")," |
36 | .BI " void *" data ");" | |
fea681da MK |
37 | .fi |
38 | .SH DESCRIPTION | |
39 | The | |
d355f1ed | 40 | .BR dl_iterate_phdr () |
cf50118f | 41 | function allows an application to inquire at run time to find |
fea681da MK |
42 | out which shared objects it has loaded. |
43 | ||
44 | The | |
d355f1ed | 45 | .BR dl_iterate_phdr () |
fea681da MK |
46 | function walks through the list of an |
47 | application's shared objects and calls the function | |
48 | .I callback | |
49 | once for each object, | |
50 | until either all shared objects have been processed or | |
51 | .I callback | |
c7094399 | 52 | returns a nonzero value. |
fea681da MK |
53 | |
54 | Each call to | |
55 | .I callback | |
56 | receives three arguments: | |
57 | .IR info , | |
58 | which is a pointer to a structure containing information | |
59 | about the shared object; | |
60 | .IR size , | |
61 | which is the size of the structure pointed to by | |
62 | .IR info ; | |
63 | and | |
64 | .IR data , | |
65 | which is a copy of whatever value was passed by the calling | |
66 | program as the second argument (also named | |
67 | .IR data ) | |
68 | in the call to | |
d355f1ed | 69 | .BR dl_iterate_phdr (). |
fea681da MK |
70 | |
71 | The | |
72 | .I info | |
73 | argument is a structure of the following type: | |
74 | ||
088a639b | 75 | .in +4n |
fea681da | 76 | .nf |
3c8e93ad | 77 | struct dl_phdr_info { |
fea681da MK |
78 | ElfW(Addr) dlpi_addr; /* Base address of object */ |
79 | const char *dlpi_name; /* (Null-terminated) name of | |
2968ea1a | 80 | object */ |
fea681da MK |
81 | const ElfW(Phdr) *dlpi_phdr; /* Pointer to array of |
82 | ELF program headers | |
83 | for this object */ | |
f81fb444 | 84 | ElfW(Half) dlpi_phnum; /* # of items in \fIdlpi_phdr\fP */ |
9b14ad2d MK |
85 | |
86 | /* The following fields were added in glibc 2.4, after the first | |
87 | version of this structure was available. Check the \fIsize\fP | |
88 | argument passed to the dl_iterate_phdr callback to determine | |
89 | whether or not each later member is available. */ | |
90 | ||
91 | unsigned long long int dlpi_adds; | |
92 | /* Incremented when a new object may | |
93 | have been added */ | |
94 | unsigned long long int dlpi_subs; | |
95 | /* Incremented when an object may | |
96 | have been removed */ | |
97 | size_t dlpi_tls_modid; | |
98 | /* If there is a PT_TLS segment, its module | |
99 | ID as used in TLS relocations, else zero */ | |
100 | void *dlpi_tls_data; | |
101 | /* The address of the calling thread's instance | |
102 | of this module's PT_TLS segment, if it has | |
103 | one and it has been allocated in the calling | |
104 | thread, otherwise a null pointer */ | |
3c8e93ad | 105 | }; |
fea681da | 106 | .fi |
3c8e93ad | 107 | .in |
fea681da MK |
108 | |
109 | (The | |
63aa9df0 | 110 | .IR ElfW () |
fea681da MK |
111 | macro definition turns its argument into the name of an ELF data |
112 | type suitable for the hardware architecture. | |
113 | For example, on a 32-bit platform, | |
48a11e1d MK |
114 | .I ElfW(Addr) |
115 | yields the data type name | |
116 | .IR Elf32_Addr . | |
fea681da MK |
117 | Further information on these types can be found in the |
118 | .IR <elf.h> " and " <link.h> | |
119 | header files.) | |
120 | ||
121 | The | |
122 | .I dlpi_addr | |
123 | field indicates the base address of the shared object | |
124 | (i.e., the difference between the virtual memory address of | |
125 | the shared object and the offset of that object in the file | |
126 | from which it was loaded). | |
127 | The | |
128 | .I dlpi_name | |
129 | field is a null-terminated string giving the pathname | |
130 | from which the shared object was loaded. | |
131 | ||
132 | To understand the meaning of the | |
133 | .I dlpi_phdr | |
134 | and | |
135 | .I dlpi_phnum | |
136 | fields, we need to be aware that an ELF shared object consists | |
137 | of a number of segments, each of which has a corresponding | |
138 | program header describing the segment. | |
139 | The | |
140 | .I dlpi_phdr | |
141 | field is a pointer to an array of the program headers for this | |
142 | shared object. | |
143 | The | |
144 | .I dlpi_phnum | |
145 | field indicates the size of this array. | |
146 | ||
147 | These program headers are structures of the following form: | |
088a639b | 148 | .in +4n |
fea681da MK |
149 | .nf |
150 | ||
3c8e93ad | 151 | typedef struct { |
fea681da MK |
152 | Elf32_Word p_type; /* Segment type */ |
153 | Elf32_Off p_offset; /* Segment file offset */ | |
154 | Elf32_Addr p_vaddr; /* Segment virtual address */ | |
155 | Elf32_Addr p_paddr; /* Segment physical address */ | |
156 | Elf32_Word p_filesz; /* Segment size in file */ | |
157 | Elf32_Word p_memsz; /* Segment size in memory */ | |
158 | Elf32_Word p_flags; /* Segment flags */ | |
159 | Elf32_Word p_align; /* Segment alignment */ | |
3c8e93ad | 160 | } Elf32_Phdr; |
fea681da | 161 | .fi |
3c8e93ad | 162 | .in |
fea681da MK |
163 | |
164 | Note that we can calculate the location of a particular program header, | |
165 | .IR x , | |
fba59d25 | 166 | in virtual memory using the formula: |
fea681da MK |
167 | |
168 | .nf | |
94e9d9fe | 169 | addr == info\->dlpi_addr + info\->dlpi_phdr[x].p_vaddr; |
fea681da | 170 | .fi |
2b2581ee MK |
171 | .SH RETURN VALUE |
172 | The | |
173 | .BR dl_iterate_phdr () | |
174 | function returns whatever value was returned by the last call to | |
175 | .IR callback . | |
24377d40 MK |
176 | .SH VERSIONS |
177 | .BR dl_iterate_phdr () | |
178 | has been supported in glibc since version 2.2.4. | |
1ee2274c ZL |
179 | .SH ATTRIBUTES |
180 | For an explanation of the terms used in this section, see | |
181 | .BR attributes (7). | |
182 | .TS | |
183 | allbox; | |
184 | lb lb lb | |
185 | l l l. | |
186 | Interface Attribute Value | |
187 | T{ | |
188 | .BR dl_iterate_phdr () | |
189 | T} Thread safety MT-Safe | |
190 | .TE | |
191 | ||
47297adb | 192 | .SH CONFORMING TO |
2b2581ee MK |
193 | The |
194 | .BR dl_iterate_phdr () | |
c9629ff8 MK |
195 | function is not specified in any standard. |
196 | Various other systems provide a version of this function, | |
197 | although details of the returned | |
198 | .I dl_phdr_info | |
199 | structure differ. | |
200 | On the BSDs and Solaris, the structure includes the fields | |
201 | .IR dlpi_addr , | |
202 | .IR dlpi_name , | |
203 | .IR dlpi_phdr , | |
204 | and | |
205 | .IR dlpi_phnum | |
206 | in addition to other implementation-specific fields. | |
70476aa4 MK |
207 | .SH NOTES |
208 | Future versions of the C library may add further fields to the | |
209 | .IR dl_phdr_info | |
210 | structure; in that event, the | |
211 | .I size | |
212 | argument provides a mechanism for the callback function to discover | |
213 | whether it is running on a system with added fields. | |
f1e1b550 MK |
214 | |
215 | The first object visited by | |
216 | .IR callback | |
217 | is the main program. | |
218 | For the main program, the | |
219 | .I dlpi_name | |
220 | field will be an empty string. | |
9b336505 | 221 | .SH EXAMPLE |
c13182ef | 222 | The following program displays a list of pathnames of the |
fea681da | 223 | shared objects it has loaded. |
c13182ef | 224 | For each shared object, the program lists the virtual addresses |
fea681da MK |
225 | at which the object's ELF segments are loaded. |
226 | ||
227 | .nf | |
228 | #define _GNU_SOURCE | |
229 | #include <link.h> | |
230 | #include <stdlib.h> | |
231 | #include <stdio.h> | |
232 | ||
233 | static int | |
234 | callback(struct dl_phdr_info *info, size_t size, void *data) | |
235 | { | |
236 | int j; | |
237 | ||
29059a65 MK |
238 | printf("name=%s (%d segments)\\n", info\->dlpi_name, |
239 | info\->dlpi_phnum); | |
fea681da | 240 | |
29059a65 | 241 | for (j = 0; j < info\->dlpi_phnum; j++) |
fea681da | 242 | printf("\\t\\t header %2d: address=%10p\\n", j, |
29059a65 | 243 | (void *) (info\->dlpi_addr + info\->dlpi_phdr[j].p_vaddr)); |
fea681da MK |
244 | return 0; |
245 | } | |
246 | ||
247 | int | |
248 | main(int argc, char *argv[]) | |
249 | { | |
250 | dl_iterate_phdr(callback, NULL); | |
251 | ||
252 | exit(EXIT_SUCCESS); | |
253 | } | |
254 | .fi | |
47297adb | 255 | .SH SEE ALSO |
fea681da MK |
256 | .BR ldd (1), |
257 | .BR objdump (1), | |
258 | .BR readelf (1), | |
a7634f01 | 259 | .BR dladdr (3), |
fea681da | 260 | .BR dlopen (3), |
3f89dd3d | 261 | .BR elf (5), |
173fe7e7 DP |
262 | .BR ld.so (8) |
263 | ||
264 | .IR "Executable and Linking Format Specification" , | |
fea681da | 265 | available at various locations online. |