Debian Codegraph @

upstream/debian-unstable/man3/dl_iterate_phdr.3

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