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