]>
Commit | Line | Data |
---|---|---|
c11b1abf | 1 | .\" Copyright (c) 2003 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
2 | .\" |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one | |
11 | .\" | |
12 | .\" Since the Linux kernel and libraries are constantly changing, this | |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. | |
16 | .\" | |
17 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
18 | .\" the source, must acknowledge the copyright and authors of this work. | |
19 | .\" License. | |
20 | .\" | |
d9343c5c | 21 | .TH DL_ITERATE_PHDR 3 2007-05-18 "GNU" "Linux Programmer's Manual" |
fea681da MK |
22 | .SH NAME |
23 | dl_iterate_phdr \- walk through list of shared objects | |
24 | .SH SYNOPSIS | |
25 | .nf | |
86c25695 | 26 | .B #define _GNU_SOURCE |
fea681da MK |
27 | .B #include <link.h> |
28 | ||
29 | \fBint dl_iterate_phdr(\fP | |
30 | \fBint (*\fPcallback\fB) \ | |
31 | (struct dl_phdr_info *\fPinfo\fB,\fP | |
32 | \fBsize_t\fP size\fB, void *\fPdata\fB),\fP | |
33 | \fBvoid *\fPdata\fB);\fP | |
34 | .fi | |
35 | .SH DESCRIPTION | |
36 | The | |
d355f1ed | 37 | .BR dl_iterate_phdr () |
fea681da MK |
38 | function allows an application to inquire at run-time to find |
39 | out which shared objects it has loaded. | |
40 | ||
41 | The | |
d355f1ed | 42 | .BR dl_iterate_phdr () |
fea681da MK |
43 | function walks through the list of an |
44 | application's shared objects and calls the function | |
45 | .I callback | |
46 | once for each object, | |
47 | until either all shared objects have been processed or | |
48 | .I callback | |
49 | returns a non-zero value. | |
50 | ||
51 | Each call to | |
52 | .I callback | |
53 | receives three arguments: | |
54 | .IR info , | |
55 | which is a pointer to a structure containing information | |
56 | about the shared object; | |
57 | .IR size , | |
58 | which is the size of the structure pointed to by | |
59 | .IR info ; | |
60 | and | |
61 | .IR data , | |
62 | which is a copy of whatever value was passed by the calling | |
63 | program as the second argument (also named | |
64 | .IR data ) | |
65 | in the call to | |
d355f1ed | 66 | .BR dl_iterate_phdr (). |
fea681da MK |
67 | |
68 | The | |
69 | .I info | |
70 | argument is a structure of the following type: | |
71 | ||
088a639b | 72 | .in +4n |
fea681da | 73 | .nf |
3c8e93ad | 74 | struct dl_phdr_info { |
fea681da MK |
75 | ElfW(Addr) dlpi_addr; /* Base address of object */ |
76 | const char *dlpi_name; /* (Null-terminated) name of | |
2968ea1a | 77 | object */ |
fea681da MK |
78 | const ElfW(Phdr) *dlpi_phdr; /* Pointer to array of |
79 | ELF program headers | |
80 | for this object */ | |
81 | ElfW(Half) dlpi_phnum; /* # of items in 'dlpi_phdr' */ | |
3c8e93ad | 82 | }; |
fea681da | 83 | .fi |
3c8e93ad | 84 | .in |
fea681da MK |
85 | |
86 | (The | |
63aa9df0 | 87 | .IR ElfW () |
fea681da MK |
88 | macro definition turns its argument into the name of an ELF data |
89 | type suitable for the hardware architecture. | |
90 | For example, on a 32-bit platform, | |
91 | ElfW(Addr) yields the data type name Elf32_Addr. | |
92 | Further information on these types can be found in the | |
93 | .IR <elf.h> " and " <link.h> | |
94 | header files.) | |
95 | ||
96 | The | |
97 | .I dlpi_addr | |
98 | field indicates the base address of the shared object | |
99 | (i.e., the difference between the virtual memory address of | |
100 | the shared object and the offset of that object in the file | |
101 | from which it was loaded). | |
102 | The | |
103 | .I dlpi_name | |
104 | field is a null-terminated string giving the pathname | |
105 | from which the shared object was loaded. | |
106 | ||
107 | To understand the meaning of the | |
108 | .I dlpi_phdr | |
109 | and | |
110 | .I dlpi_phnum | |
111 | fields, we need to be aware that an ELF shared object consists | |
112 | of a number of segments, each of which has a corresponding | |
113 | program header describing the segment. | |
114 | The | |
115 | .I dlpi_phdr | |
116 | field is a pointer to an array of the program headers for this | |
117 | shared object. | |
118 | The | |
119 | .I dlpi_phnum | |
120 | field indicates the size of this array. | |
121 | ||
122 | These program headers are structures of the following form: | |
088a639b | 123 | .in +4n |
fea681da MK |
124 | .nf |
125 | ||
3c8e93ad | 126 | typedef struct { |
fea681da MK |
127 | Elf32_Word p_type; /* Segment type */ |
128 | Elf32_Off p_offset; /* Segment file offset */ | |
129 | Elf32_Addr p_vaddr; /* Segment virtual address */ | |
130 | Elf32_Addr p_paddr; /* Segment physical address */ | |
131 | Elf32_Word p_filesz; /* Segment size in file */ | |
132 | Elf32_Word p_memsz; /* Segment size in memory */ | |
133 | Elf32_Word p_flags; /* Segment flags */ | |
134 | Elf32_Word p_align; /* Segment alignment */ | |
3c8e93ad | 135 | } Elf32_Phdr; |
fea681da | 136 | .fi |
3c8e93ad | 137 | .in |
fea681da MK |
138 | |
139 | Note that we can calculate the location of a particular program header, | |
140 | .IR x , | |
fba59d25 | 141 | in virtual memory using the formula: |
fea681da MK |
142 | |
143 | .nf | |
94e9d9fe | 144 | addr == info\->dlpi_addr + info\->dlpi_phdr[x].p_vaddr; |
fea681da | 145 | .fi |
2b2581ee MK |
146 | .SH RETURN VALUE |
147 | The | |
148 | .BR dl_iterate_phdr () | |
149 | function returns whatever value was returned by the last call to | |
150 | .IR callback . | |
24377d40 MK |
151 | .SH VERSIONS |
152 | .BR dl_iterate_phdr () | |
153 | has been supported in glibc since version 2.2.4. | |
2b2581ee MK |
154 | .SH "CONFORMING TO" |
155 | The | |
156 | .BR dl_iterate_phdr () | |
8382f16d | 157 | function is Linux-specific and should be avoided in portable applications. |
9b336505 | 158 | .SH EXAMPLE |
c13182ef | 159 | The following program displays a list of pathnames of the |
fea681da | 160 | shared objects it has loaded. |
c13182ef | 161 | For each shared object, the program lists the virtual addresses |
fea681da MK |
162 | at which the object's ELF segments are loaded. |
163 | ||
164 | .nf | |
165 | #define _GNU_SOURCE | |
166 | #include <link.h> | |
167 | #include <stdlib.h> | |
168 | #include <stdio.h> | |
169 | ||
170 | static int | |
171 | callback(struct dl_phdr_info *info, size_t size, void *data) | |
172 | { | |
173 | int j; | |
174 | ||
29059a65 MK |
175 | printf("name=%s (%d segments)\\n", info\->dlpi_name, |
176 | info\->dlpi_phnum); | |
fea681da | 177 | |
29059a65 | 178 | for (j = 0; j < info\->dlpi_phnum; j++) |
fea681da | 179 | printf("\\t\\t header %2d: address=%10p\\n", j, |
29059a65 | 180 | (void *) (info\->dlpi_addr + info\->dlpi_phdr[j].p_vaddr)); |
fea681da MK |
181 | return 0; |
182 | } | |
183 | ||
184 | int | |
185 | main(int argc, char *argv[]) | |
186 | { | |
187 | dl_iterate_phdr(callback, NULL); | |
188 | ||
189 | exit(EXIT_SUCCESS); | |
190 | } | |
191 | .fi | |
fea681da MK |
192 | .SH "SEE ALSO" |
193 | .BR ldd (1), | |
194 | .BR objdump (1), | |
195 | .BR readelf (1), | |
196 | .BR dlopen (3), | |
0a90178c | 197 | .BR feature_test_macros (7), |
fea681da MK |
198 | .BR ld.so (8), |
199 | and the | |
200 | .I "Executable and Linking Format Specification" | |
201 | available at various locations online. |