Debian Codegraph @

upstream/debian-trixie/man3/dl_iterate_phdr.3

raw
1 '\" t
2 .\" Copyright (c) 2003, 2017 by Michael Kerrisk <[email protected]>
3 .\"
4 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
5 .\"
6 .TH dl_iterate_phdr 3 2024-06-15 "Linux man-pages 6.9.1"
7 .SH NAME
8 dl_iterate_phdr \- walk through list of shared objects
9 .SH LIBRARY
10 Standard C library
11 .RI ( libc ", " \-lc )
12 .SH SYNOPSIS
13 .nf
14 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
15 .B #include <link.h>
16 .P
17 .B int dl_iterate_phdr(
18 .BI " int (*" callback ")(struct dl_phdr_info *" info ,
19 .BI " size_t " size ", void *" data ),
20 .BI " void *" data );
21 .fi
22 .SH DESCRIPTION
23 The
24 .BR dl_iterate_phdr ()
25 function allows an application to inquire at run time to find
26 out which shared objects it has loaded,
27 and the order in which they were loaded.
28 .P
29 The
30 .BR dl_iterate_phdr ()
31 function walks through the list of an
32 application's shared objects and calls the function
33 .I callback
34 once for each object,
35 until either all shared objects have been processed or
36 .I callback
37 returns a nonzero value.
38 .P
39 Each call to
40 .I callback
41 receives three arguments:
42 .IR info ,
43 which is a pointer to a structure containing information
44 about the shared object;
45 .IR size ,
46 which is the size of the structure pointed to by
47 .IR info ;
48 and
49 .IR data ,
50 which is a copy of whatever value was passed by the calling
51 program as the second argument (also named
52 .IR data )
53 in the call to
54 .BR dl_iterate_phdr ().
55 .P
56 The
57 .I info
58 argument is a structure of the following type:
59 .P
60 .in +4n
61 .EX
62 struct dl_phdr_info {
63 ElfW(Addr) dlpi_addr; /* Base address of object */
64 const char *dlpi_name; /* (Null\-terminated) name of
65 object */
66 const ElfW(Phdr) *dlpi_phdr; /* Pointer to array of
67 ELF program headers
68 for this object */
69 ElfW(Half) dlpi_phnum; /* # of items in \fIdlpi_phdr\fP */
70 \&
71 /* The following fields were added in glibc 2.4, after the first
72 version of this structure was available. Check the \fIsize\fP
73 argument passed to the dl_iterate_phdr callback to determine
74 whether or not each later member is available. */
75 \&
76 unsigned long long dlpi_adds;
77 /* Incremented when a new object may
78 have been added */
79 unsigned long long dlpi_subs;
80 /* Incremented when an object may
81 have been removed */
82 size_t dlpi_tls_modid;
83 /* If there is a PT_TLS segment, its module
84 ID as used in TLS relocations, else zero */
85 void *dlpi_tls_data;
86 /* The address of the calling thread\[aq]s instance
87 of this module\[aq]s PT_TLS segment, if it has
88 one and it has been allocated in the calling
89 thread, otherwise a null pointer */
90 };
91 .EE
92 .in
93 .P
94 (The
95 .IR ElfW ()
96 macro definition turns its argument into the name of an ELF data
97 type suitable for the hardware architecture.
98 For example, on a 32-bit platform,
99 .I ElfW(Addr)
100 yields the data type name
101 .IR Elf32_Addr .
102 Further information on these types can be found in the
103 .IR <elf.h> " and " <link.h>
104 header files.)
105 .P
106 The
107 .I dlpi_addr
108 field indicates the base address of the shared object
109 (i.e., the difference between the virtual memory address of
110 the shared object and the offset of that object in the file
111 from which it was loaded).
112 The
113 .I dlpi_name
114 field is a null-terminated string giving the pathname
115 from which the shared object was loaded.
116 .P
117 To understand the meaning of the
118 .I dlpi_phdr
119 and
120 .I dlpi_phnum
121 fields, we need to be aware that an ELF shared object consists
122 of a number of segments, each of which has a corresponding
123 program header describing the segment.
124 The
125 .I dlpi_phdr
126 field is a pointer to an array of the program headers for this
127 shared object.
128 The
129 .I dlpi_phnum
130 field indicates the size of this array.
131 .P
132 These program headers are structures of the following form:
133 .P
134 .in +4n
135 .EX
136 typedef struct {
137 Elf32_Word p_type; /* Segment type */
138 Elf32_Off p_offset; /* Segment file offset */
139 Elf32_Addr p_vaddr; /* Segment virtual address */
140 Elf32_Addr p_paddr; /* Segment physical address */
141 Elf32_Word p_filesz; /* Segment size in file */
142 Elf32_Word p_memsz; /* Segment size in memory */
143 Elf32_Word p_flags; /* Segment flags */
144 Elf32_Word p_align; /* Segment alignment */
145 } Elf32_Phdr;
146 .EE
147 .in
148 .P
149 Note that we can calculate the location of a particular program header,
150 .IR x ,
151 in virtual memory using the formula:
152 .P
153 .in +4n
154 .EX
155 addr == info\->dlpi_addr + info\->dlpi_phdr[x].p_vaddr;
156 .EE
157 .in
158 .P
159 Possible values for
160 .I p_type
161 include the following (see
162 .I <elf.h>
163 for further details):
164 .P
165 .in +4n
166 .EX
167 #define PT_LOAD 1 /* Loadable program segment */
168 #define PT_DYNAMIC 2 /* Dynamic linking information */
169 #define PT_INTERP 3 /* Program interpreter */
170 #define PT_NOTE 4 /* Auxiliary information */
171 #define PT_SHLIB 5 /* Reserved */
172 #define PT_PHDR 6 /* Entry for header table itself */
173 #define PT_TLS 7 /* Thread\-local storage segment */
174 #define PT_GNU_EH_FRAME 0x6474e550 /* GCC .eh_frame_hdr segment */
175 #define PT_GNU_STACK 0x6474e551 /* Indicates stack executability */
176 .\" For PT_GNU_STACK, see http://www.airs.com/blog/archives/518
177 #define PT_GNU_RELRO 0x6474e552 /* Read\-only after relocation */
178 .EE
179 .in
180 .SH RETURN VALUE
181 The
182 .BR dl_iterate_phdr ()
183 function returns whatever value was returned by the last call to
184 .IR callback .
185 .SH ATTRIBUTES
186 For an explanation of the terms used in this section, see
187 .BR attributes (7).
188 .TS
189 allbox;
190 lbx lb lb
191 l l l.
192 Interface Attribute Value
193 T{
194 .na
195 .nh
196 .BR dl_iterate_phdr ()
197 T} Thread safety MT-Safe
198 .TE
199 .SH VERSIONS
200 Various other systems provide a version of this function,
201 although details of the returned
202 .I dl_phdr_info
203 structure differ.
204 On the BSDs and Solaris, the structure includes the fields
205 .IR dlpi_addr ,
206 .IR dlpi_name ,
207 .IR dlpi_phdr ,
208 and
209 .I dlpi_phnum
210 in addition to other implementation-specific fields.
211 .P
212 Future versions of the C library may add further fields to the
213 .I dl_phdr_info
214 structure; in that event, the
215 .I size
216 argument provides a mechanism for the callback function to discover
217 whether it is running on a system with added fields.
218 .SH STANDARDS
219 None.
220 .SH HISTORY
221 glibc 2.2.4.
222 .SH NOTES
223 The first object visited by
224 .I callback
225 is the main program.
226 For the main program, the
227 .I dlpi_name
228 field will be an empty string.
229 .SH EXAMPLES
230 The following program displays a list of pathnames of the
231 shared objects it has loaded.
232 For each shared object, the program lists some information
233 (virtual address, size, flags, and type)
234 for each of the objects ELF segments.
235 .P
236 The following shell session demonstrates the output
237 produced by the program on an x86-64 system.
238 The first shared object for which output is displayed
239 (where the name is an empty string)
240 is the main program.
241 .P
242 .in +4n
243 .EX
244 $ \fB./a.out\fP
245 Name: "" (9 segments)
246 0: [ 0x400040; memsz: 1f8] flags: 0x5; PT_PHDR
247 1: [ 0x400238; memsz: 1c] flags: 0x4; PT_INTERP
248 2: [ 0x400000; memsz: ac4] flags: 0x5; PT_LOAD
249 3: [ 0x600e10; memsz: 240] flags: 0x6; PT_LOAD
250 4: [ 0x600e28; memsz: 1d0] flags: 0x6; PT_DYNAMIC
251 5: [ 0x400254; memsz: 44] flags: 0x4; PT_NOTE
252 6: [ 0x400970; memsz: 3c] flags: 0x4; PT_GNU_EH_FRAME
253 7: [ (nil); memsz: 0] flags: 0x6; PT_GNU_STACK
254 8: [ 0x600e10; memsz: 1f0] flags: 0x4; PT_GNU_RELRO
255 Name: "linux\-vdso.so.1" (4 segments)
256 0: [0x7ffc6edd1000; memsz: e89] flags: 0x5; PT_LOAD
257 1: [0x7ffc6edd1360; memsz: 110] flags: 0x4; PT_DYNAMIC
258 2: [0x7ffc6edd17b0; memsz: 3c] flags: 0x4; PT_NOTE
259 3: [0x7ffc6edd17ec; memsz: 3c] flags: 0x4; PT_GNU_EH_FRAME
260 Name: "/lib64/libc.so.6" (10 segments)
261 0: [0x7f55712ce040; memsz: 230] flags: 0x5; PT_PHDR
262 1: [0x7f557145b980; memsz: 1c] flags: 0x4; PT_INTERP
263 2: [0x7f55712ce000; memsz: 1b6a5c] flags: 0x5; PT_LOAD
264 3: [0x7f55716857a0; memsz: 9240] flags: 0x6; PT_LOAD
265 4: [0x7f5571688b80; memsz: 1f0] flags: 0x6; PT_DYNAMIC
266 5: [0x7f55712ce270; memsz: 44] flags: 0x4; PT_NOTE
267 6: [0x7f55716857a0; memsz: 78] flags: 0x4; PT_TLS
268 7: [0x7f557145b99c; memsz: 544c] flags: 0x4; PT_GNU_EH_FRAME
269 8: [0x7f55712ce000; memsz: 0] flags: 0x6; PT_GNU_STACK
270 9: [0x7f55716857a0; memsz: 3860] flags: 0x4; PT_GNU_RELRO
271 Name: "/lib64/ld\-linux\-x86\-64.so.2" (7 segments)
272 0: [0x7f557168f000; memsz: 20828] flags: 0x5; PT_LOAD
273 1: [0x7f55718afba0; memsz: 15a8] flags: 0x6; PT_LOAD
274 2: [0x7f55718afe10; memsz: 190] flags: 0x6; PT_DYNAMIC
275 3: [0x7f557168f1c8; memsz: 24] flags: 0x4; PT_NOTE
276 4: [0x7f55716acec4; memsz: 604] flags: 0x4; PT_GNU_EH_FRAME
277 5: [0x7f557168f000; memsz: 0] flags: 0x6; PT_GNU_STACK
278 6: [0x7f55718afba0; memsz: 460] flags: 0x4; PT_GNU_RELRO
279 .EE
280 .in
281 .SS Program source
282 \&
283 .\" SRC BEGIN (dl_iterate_phdr.c)
284 .EX
285 #define _GNU_SOURCE
286 #include <link.h>
287 #include <stdint.h>
288 #include <stdio.h>
289 #include <stdlib.h>
290 \&
291 static int
292 callback(struct dl_phdr_info *info, size_t size, void *data)
293 {
294 char *type;
295 int p_type;
296 \&
297 printf("Name: \[rs]"%s\[rs]" (%d segments)\[rs]n", info\->dlpi_name,
298 info\->dlpi_phnum);
299 \&
300 for (size_t j = 0; j < info\->dlpi_phnum; j++) {
301 p_type = info\->dlpi_phdr[j].p_type;
302 type = (p_type == PT_LOAD) ? "PT_LOAD" :
303 (p_type == PT_DYNAMIC) ? "PT_DYNAMIC" :
304 (p_type == PT_INTERP) ? "PT_INTERP" :
305 (p_type == PT_NOTE) ? "PT_NOTE" :
306 (p_type == PT_INTERP) ? "PT_INTERP" :
307 (p_type == PT_PHDR) ? "PT_PHDR" :
308 (p_type == PT_TLS) ? "PT_TLS" :
309 (p_type == PT_GNU_EH_FRAME) ? "PT_GNU_EH_FRAME" :
310 (p_type == PT_GNU_STACK) ? "PT_GNU_STACK" :
311 (p_type == PT_GNU_RELRO) ? "PT_GNU_RELRO" : NULL;
312 \&
313 printf(" %2zu: [%14p; memsz:%7jx] flags: %#jx; ", j,
314 (void *) (info\->dlpi_addr + info\->dlpi_phdr[j].p_vaddr),
315 (uintmax_t) info\->dlpi_phdr[j].p_memsz,
316 (uintmax_t) info\->dlpi_phdr[j].p_flags);
317 if (type != NULL)
318 printf("%s\[rs]n", type);
319 else
320 printf("[other (%#x)]\[rs]n", p_type);
321 }
322 \&
323 return 0;
324 }
325 \&
326 int
327 main(void)
328 {
329 dl_iterate_phdr(callback, NULL);
330 \&
331 exit(EXIT_SUCCESS);
332 }
333 .EE
334 .\" SRC END
335 .SH SEE ALSO
336 .BR ldd (1),
337 .BR objdump (1),
338 .BR readelf (1),
339 .BR dladdr (3),
340 .BR dlopen (3),
341 .BR elf (5),
342 .BR ld.so (8)
343 .P
344 .IR "Executable and Linking Format Specification" ,
345 available at various locations online.