| 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. |