1 .\" Copyright (c) 2003, 2017 by Michael Kerrisk <mtk.manpages@gmail.com>
3 .\" %%%LICENSE_START(VERBATIM)
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.
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
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
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
21 .\" Formatted or processed versions of this manual, if unaccompanied by
22 .\" the source, must acknowledge the copyright and authors of this work.
25 .TH DL_ITERATE_PHDR 3 2021-03-22 "GNU" "Linux Programmer's Manual"
27 dl_iterate_phdr \- walk through list of shared objects
30 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
33 .BI "int dl_iterate_phdr("
34 .BI " int (*" callback ")(struct dl_phdr_info *" info ,
35 .BI " size_t " size ", void *" data "),"
36 .BI " void *" data ");"
40 .BR dl_iterate_phdr ()
41 function allows an application to inquire at run time to find
42 out which shared objects it has loaded,
43 and the order in which they were loaded.
46 .BR dl_iterate_phdr ()
47 function walks through the list of an
48 application's shared objects and calls the function
51 until either all shared objects have been processed or
53 returns a nonzero value.
57 receives three arguments:
59 which is a pointer to a structure containing information
60 about the shared object;
62 which is the size of the structure pointed to by
66 which is a copy of whatever value was passed by the calling
67 program as the second argument (also named
70 .BR dl_iterate_phdr ().
74 argument is a structure of the following type:
79 ElfW(Addr) dlpi_addr; /* Base address of object */
80 const char *dlpi_name; /* (Null\-terminated) name of
82 const ElfW(Phdr) *dlpi_phdr; /* Pointer to array of
85 ElfW(Half) dlpi_phnum; /* # of items in \fIdlpi_phdr\fP */
87 /* The following fields were added in glibc 2.4, after the first
88 version of this structure was available. Check the \fIsize\fP
89 argument passed to the dl_iterate_phdr callback to determine
90 whether or not each later member is available. */
92 unsigned long long dlpi_adds;
93 /* Incremented when a new object may
95 unsigned long long dlpi_subs;
96 /* Incremented when an object may
98 size_t dlpi_tls_modid;
99 /* If there is a PT_TLS segment, its module
100 ID as used in TLS relocations, else zero */
102 /* The address of the calling thread\(aqs instance
103 of this module\(aqs PT_TLS segment, if it has
104 one and it has been allocated in the calling
105 thread, otherwise a null pointer */
112 macro definition turns its argument into the name of an ELF data
113 type suitable for the hardware architecture.
114 For example, on a 32-bit platform,
116 yields the data type name
118 Further information on these types can be found in the
119 .IR <elf.h> " and " <link.h>
124 field indicates the base address of the shared object
125 (i.e., the difference between the virtual memory address of
126 the shared object and the offset of that object in the file
127 from which it was loaded).
130 field is a null-terminated string giving the pathname
131 from which the shared object was loaded.
133 To understand the meaning of the
137 fields, we need to be aware that an ELF shared object consists
138 of a number of segments, each of which has a corresponding
139 program header describing the segment.
142 field is a pointer to an array of the program headers for this
146 field indicates the size of this array.
148 These program headers are structures of the following form:
153 Elf32_Word p_type; /* Segment type */
154 Elf32_Off p_offset; /* Segment file offset */
155 Elf32_Addr p_vaddr; /* Segment virtual address */
156 Elf32_Addr p_paddr; /* Segment physical address */
157 Elf32_Word p_filesz; /* Segment size in file */
158 Elf32_Word p_memsz; /* Segment size in memory */
159 Elf32_Word p_flags; /* Segment flags */
160 Elf32_Word p_align; /* Segment alignment */
165 Note that we can calculate the location of a particular program header,
167 in virtual memory using the formula:
171 addr == info\->dlpi_addr + info\->dlpi_phdr[x].p_vaddr;
177 include the following (see
179 for further details):
183 #define PT_LOAD 1 /* Loadable program segment */
184 #define PT_DYNAMIC 2 /* Dynamic linking information */
185 #define PT_INTERP 3 /* Program interpreter */
186 #define PT_NOTE 4 /* Auxiliary information */
187 #define PT_SHLIB 5 /* Reserved */
188 #define PT_PHDR 6 /* Entry for header table itself */
189 #define PT_TLS 7 /* Thread\-local storage segment */
190 #define PT_GNU_EH_FRAME 0x6474e550 /* GCC .eh_frame_hdr segment */
191 #define PT_GNU_STACK 0x6474e551 /* Indicates stack executability */
192 .\" For PT_GNU_STACK, see http://www.airs.com/blog/archives/518
193 #define PT_GNU_RELRO 0x6474e552 /* Read\-only after relocation */
198 .BR dl_iterate_phdr ()
199 function returns whatever value was returned by the last call to
202 .BR dl_iterate_phdr ()
203 has been supported in glibc since version 2.2.4.
205 For an explanation of the terms used in this section, see
213 Interface Attribute Value
215 .BR dl_iterate_phdr ()
216 T} Thread safety MT-Safe
223 .BR dl_iterate_phdr ()
224 function is not specified in any standard.
225 Various other systems provide a version of this function,
226 although details of the returned
229 On the BSDs and Solaris, the structure includes the fields
235 in addition to other implementation-specific fields.
237 Future versions of the C library may add further fields to the
239 structure; in that event, the
241 argument provides a mechanism for the callback function to discover
242 whether it is running on a system with added fields.
244 The first object visited by
247 For the main program, the
249 field will be an empty string.
251 The following program displays a list of pathnames of the
252 shared objects it has loaded.
253 For each shared object, the program lists some information
254 (virtual address, size, flags, and type)
255 for each of the objects ELF segments.
257 The following shell session demonstrates the output
258 produced by the program on an x86-64 system.
259 The first shared object for which output is displayed
260 (where the name is an empty string)
266 Name: "" (9 segments)
267 0: [ 0x400040; memsz: 1f8] flags: 0x5; PT_PHDR
268 1: [ 0x400238; memsz: 1c] flags: 0x4; PT_INTERP
269 2: [ 0x400000; memsz: ac4] flags: 0x5; PT_LOAD
270 3: [ 0x600e10; memsz: 240] flags: 0x6; PT_LOAD
271 4: [ 0x600e28; memsz: 1d0] flags: 0x6; PT_DYNAMIC
272 5: [ 0x400254; memsz: 44] flags: 0x4; PT_NOTE
273 6: [ 0x400970; memsz: 3c] flags: 0x4; PT_GNU_EH_FRAME
274 7: [ (nil); memsz: 0] flags: 0x6; PT_GNU_STACK
275 8: [ 0x600e10; memsz: 1f0] flags: 0x4; PT_GNU_RELRO
276 Name: "linux\-vdso.so.1" (4 segments)
277 0: [0x7ffc6edd1000; memsz: e89] flags: 0x5; PT_LOAD
278 1: [0x7ffc6edd1360; memsz: 110] flags: 0x4; PT_DYNAMIC
279 2: [0x7ffc6edd17b0; memsz: 3c] flags: 0x4; PT_NOTE
280 3: [0x7ffc6edd17ec; memsz: 3c] flags: 0x4; PT_GNU_EH_FRAME
281 Name: "/lib64/libc.so.6" (10 segments)
282 0: [0x7f55712ce040; memsz: 230] flags: 0x5; PT_PHDR
283 1: [0x7f557145b980; memsz: 1c] flags: 0x4; PT_INTERP
284 2: [0x7f55712ce000; memsz: 1b6a5c] flags: 0x5; PT_LOAD
285 3: [0x7f55716857a0; memsz: 9240] flags: 0x6; PT_LOAD
286 4: [0x7f5571688b80; memsz: 1f0] flags: 0x6; PT_DYNAMIC
287 5: [0x7f55712ce270; memsz: 44] flags: 0x4; PT_NOTE
288 6: [0x7f55716857a0; memsz: 78] flags: 0x4; PT_TLS
289 7: [0x7f557145b99c; memsz: 544c] flags: 0x4; PT_GNU_EH_FRAME
290 8: [0x7f55712ce000; memsz: 0] flags: 0x6; PT_GNU_STACK
291 9: [0x7f55716857a0; memsz: 3860] flags: 0x4; PT_GNU_RELRO
292 Name: "/lib64/ld\-linux\-x86\-64.so.2" (7 segments)
293 0: [0x7f557168f000; memsz: 20828] flags: 0x5; PT_LOAD
294 1: [0x7f55718afba0; memsz: 15a8] flags: 0x6; PT_LOAD
295 2: [0x7f55718afe10; memsz: 190] flags: 0x6; PT_DYNAMIC
296 3: [0x7f557168f1c8; memsz: 24] flags: 0x4; PT_NOTE
297 4: [0x7f55716acec4; memsz: 604] flags: 0x4; PT_GNU_EH_FRAME
298 5: [0x7f557168f000; memsz: 0] flags: 0x6; PT_GNU_STACK
299 6: [0x7f55718afba0; memsz: 460] flags: 0x4; PT_GNU_RELRO
312 callback(struct dl_phdr_info *info, size_t size, void *data)
317 printf("Name: \e"%s\e" (%d segments)\en", info\->dlpi_name,
320 for (int j = 0; j < info\->dlpi_phnum; j++) {
321 p_type = info\->dlpi_phdr[j].p_type;
322 type = (p_type == PT_LOAD) ? "PT_LOAD" :
323 (p_type == PT_DYNAMIC) ? "PT_DYNAMIC" :
324 (p_type == PT_INTERP) ? "PT_INTERP" :
325 (p_type == PT_NOTE) ? "PT_NOTE" :
326 (p_type == PT_INTERP) ? "PT_INTERP" :
327 (p_type == PT_PHDR) ? "PT_PHDR" :
328 (p_type == PT_TLS) ? "PT_TLS" :
329 (p_type == PT_GNU_EH_FRAME) ? "PT_GNU_EH_FRAME" :
330 (p_type == PT_GNU_STACK) ? "PT_GNU_STACK" :
331 (p_type == PT_GNU_RELRO) ? "PT_GNU_RELRO" : NULL;
333 printf(" %2d: [%14p; memsz:%7jx] flags: %#jx; ", j,
334 (void *) (info\->dlpi_addr + info\->dlpi_phdr[j].p_vaddr),
335 (uintmax_t) info\->dlpi_phdr[j].p_memsz,
336 (uintmax_t) info\->dlpi_phdr[j].p_flags);
338 printf("%s\en", type);
340 printf("[other (%#x)]\en", p_type);
347 main(int argc, char *argv[])
349 dl_iterate_phdr(callback, NULL);
363 .IR "Executable and Linking Format Specification" ,
364 available at various locations online.