1dl_iterate_phdr(3)         Library Functions Manual         dl_iterate_phdr(3)
2
3
4

NAME

6       dl_iterate_phdr - walk through list of shared objects
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #define _GNU_SOURCE         /* See feature_test_macros(7) */
13       #include <link.h>
14
15       int dl_iterate_phdr(
16                 int (*callback)(struct dl_phdr_info *info,
17                                 size_t size, void *data),
18                 void *data);
19

DESCRIPTION

21       The  dl_iterate_phdr() function allows an application to inquire at run
22       time to find out which shared objects it has loaded, and the  order  in
23       which they were loaded.
24
25       The  dl_iterate_phdr()  function  walks through the list of an applica‐
26       tion's shared objects and calls the function callback once for each ob‐
27       ject,  until  either all shared objects have been processed or callback
28       returns a nonzero value.
29
30       Each call to callback  receives  three  arguments:  info,  which  is  a
31       pointer  to a structure containing information about the shared object;
32       size, which is the size of the structure pointed to by info; and  data,
33       which  is a copy of whatever value was passed by the calling program as
34       the second argument (also named data) in the call to dl_iterate_phdr().
35
36       The info argument is a structure of the following type:
37
38           struct dl_phdr_info {
39               ElfW(Addr)        dlpi_addr;  /* Base address of object */
40               const char       *dlpi_name;  /* (Null-terminated) name of
41                                                object */
42               const ElfW(Phdr) *dlpi_phdr;  /* Pointer to array of
43                                                ELF program headers
44                                                for this object */
45               ElfW(Half)        dlpi_phnum; /* # of items in dlpi_phdr */
46
47               /* The following fields were added in glibc 2.4, after the first
48                  version of this structure was available.  Check the size
49                  argument passed to the dl_iterate_phdr callback to determine
50                  whether or not each later member is available.  */
51
52               unsigned long long dlpi_adds;
53                               /* Incremented when a new object may
54                                  have been added */
55               unsigned long long dlpi_subs;
56                               /* Incremented when an object may
57                                  have been removed */
58               size_t dlpi_tls_modid;
59                               /* If there is a PT_TLS segment, its module
60                                  ID as used in TLS relocations, else zero */
61               void  *dlpi_tls_data;
62                               /* The address of the calling thread's instance
63                                  of this module's PT_TLS segment, if it has
64                                  one and it has been allocated in the calling
65                                  thread, otherwise a null pointer */
66           };
67
68       (The ElfW() macro definition turns its argument into the name of an ELF
69       data  type  suitable  for the hardware architecture.  For example, on a
70       32-bit platform, ElfW(Addr) yields the data type name Elf32_Addr.  Fur‐
71       ther  information  on  these  types  can  be  found  in the <elf.h> and
72       <link.h> header files.)
73
74       The dlpi_addr field indicates the base address  of  the  shared  object
75       (i.e.,  the difference between the virtual memory address of the shared
76       object and the offset of that object in the  file  from  which  it  was
77       loaded).   The  dlpi_name  field is a null-terminated string giving the
78       pathname from which the shared object was loaded.
79
80       To understand the meaning of the dlpi_phdr and  dlpi_phnum  fields,  we
81       need to be aware that an ELF shared object consists of a number of seg‐
82       ments, each of which has a corresponding program header describing  the
83       segment.   The  dlpi_phdr field is a pointer to an array of the program
84       headers for this shared object.  The  dlpi_phnum  field  indicates  the
85       size of this array.
86
87       These program headers are structures of the following form:
88
89           typedef struct {
90               Elf32_Word  p_type;    /* Segment type */
91               Elf32_Off   p_offset;  /* Segment file offset */
92               Elf32_Addr  p_vaddr;   /* Segment virtual address */
93               Elf32_Addr  p_paddr;   /* Segment physical address */
94               Elf32_Word  p_filesz;  /* Segment size in file */
95               Elf32_Word  p_memsz;   /* Segment size in memory */
96               Elf32_Word  p_flags;   /* Segment flags */
97               Elf32_Word  p_align;   /* Segment alignment */
98           } Elf32_Phdr;
99
100       Note that we can calculate the location of a particular program header,
101       x, in virtual memory using the formula:
102
103           addr == info->dlpi_addr + info->dlpi_phdr[x].p_vaddr;
104
105       Possible values for p_type include the following (see <elf.h> for  fur‐
106       ther details):
107
108           #define PT_LOAD         1    /* Loadable program segment */
109           #define PT_DYNAMIC      2    /* Dynamic linking information */
110           #define PT_INTERP       3    /* Program interpreter */
111           #define PT_NOTE         4    /* Auxiliary information */
112           #define PT_SHLIB        5    /* Reserved */
113           #define PT_PHDR         6    /* Entry for header table itself */
114           #define PT_TLS          7    /* Thread-local storage segment */
115           #define PT_GNU_EH_FRAME 0x6474e550 /* GCC .eh_frame_hdr segment */
116           #define PT_GNU_STACK  0x6474e551 /* Indicates stack executability */
117           #define PT_GNU_RELRO  0x6474e552 /* Read-only after relocation */
118

RETURN VALUE

120       The  dl_iterate_phdr()  function returns whatever value was returned by
121       the last call to callback.
122

ATTRIBUTES

124       For an  explanation  of  the  terms  used  in  this  section,  see  at‐
125       tributes(7).
126
127       ┌────────────────────────────────────────────┬───────────────┬─────────┐
128Interface                                   Attribute     Value   
129       ├────────────────────────────────────────────┼───────────────┼─────────┤
130dl_iterate_phdr()                           │ Thread safety │ MT-Safe │
131       └────────────────────────────────────────────┴───────────────┴─────────┘
132

VERSIONS

134       Various  other  systems  provide  a  version of this function, although
135       details of the returned dl_phdr_info structure differ.  On the BSDs and
136       Solaris,  the  structure  includes  the  fields  dlpi_addr,  dlpi_name,
137       dlpi_phdr, and dlpi_phnum in addition to other  implementation-specific
138       fields.
139
140       Future  versions  of  the  C  library  may  add  further  fields to the
141       dl_phdr_info structure; in that event, the  size  argument  provides  a
142       mechanism  for  the callback function to discover whether it is running
143       on a system with added fields.
144

STANDARDS

146       None.
147

HISTORY

149       glibc 2.2.4.
150

NOTES

152       The first object visited by callback is the main program.  For the main
153       program, the dlpi_name field will be an empty string.
154

EXAMPLES

156       The  following  program  displays  a  list  of  pathnames of the shared
157       objects it has loaded.  For each shared object, the program lists  some
158       information  (virtual  address,  size, flags, and type) for each of the
159       objects ELF segments.
160
161       The following shell session demonstrates the  output  produced  by  the
162       program  on an x86-64 system.  The first shared object for which output
163       is displayed (where the name is an empty string) is the main program.
164
165           $ ./a.out
166           Name: "" (9 segments)
167                0: [      0x400040; memsz:    1f8] flags: 0x5; PT_PHDR
168                1: [      0x400238; memsz:     1c] flags: 0x4; PT_INTERP
169                2: [      0x400000; memsz:    ac4] flags: 0x5; PT_LOAD
170                3: [      0x600e10; memsz:    240] flags: 0x6; PT_LOAD
171                4: [      0x600e28; memsz:    1d0] flags: 0x6; PT_DYNAMIC
172                5: [      0x400254; memsz:     44] flags: 0x4; PT_NOTE
173                6: [      0x400970; memsz:     3c] flags: 0x4; PT_GNU_EH_FRAME
174                7: [         (nil); memsz:      0] flags: 0x6; PT_GNU_STACK
175                8: [      0x600e10; memsz:    1f0] flags: 0x4; PT_GNU_RELRO
176           Name: "linux-vdso.so.1" (4 segments)
177                0: [0x7ffc6edd1000; memsz:    e89] flags: 0x5; PT_LOAD
178                1: [0x7ffc6edd1360; memsz:    110] flags: 0x4; PT_DYNAMIC
179                2: [0x7ffc6edd17b0; memsz:     3c] flags: 0x4; PT_NOTE
180                3: [0x7ffc6edd17ec; memsz:     3c] flags: 0x4; PT_GNU_EH_FRAME
181           Name: "/lib64/libc.so.6" (10 segments)
182                0: [0x7f55712ce040; memsz:    230] flags: 0x5; PT_PHDR
183                1: [0x7f557145b980; memsz:     1c] flags: 0x4; PT_INTERP
184                2: [0x7f55712ce000; memsz: 1b6a5c] flags: 0x5; PT_LOAD
185                3: [0x7f55716857a0; memsz:   9240] flags: 0x6; PT_LOAD
186                4: [0x7f5571688b80; memsz:    1f0] flags: 0x6; PT_DYNAMIC
187                5: [0x7f55712ce270; memsz:     44] flags: 0x4; PT_NOTE
188                6: [0x7f55716857a0; memsz:     78] flags: 0x4; PT_TLS
189                7: [0x7f557145b99c; memsz:   544c] flags: 0x4; PT_GNU_EH_FRAME
190                8: [0x7f55712ce000; memsz:      0] flags: 0x6; PT_GNU_STACK
191                9: [0x7f55716857a0; memsz:   3860] flags: 0x4; PT_GNU_RELRO
192           Name: "/lib64/ld-linux-x86-64.so.2" (7 segments)
193                0: [0x7f557168f000; memsz:  20828] flags: 0x5; PT_LOAD
194                1: [0x7f55718afba0; memsz:   15a8] flags: 0x6; PT_LOAD
195                2: [0x7f55718afe10; memsz:    190] flags: 0x6; PT_DYNAMIC
196                3: [0x7f557168f1c8; memsz:     24] flags: 0x4; PT_NOTE
197                4: [0x7f55716acec4; memsz:    604] flags: 0x4; PT_GNU_EH_FRAME
198                5: [0x7f557168f000; memsz:      0] flags: 0x6; PT_GNU_STACK
199                6: [0x7f55718afba0; memsz:    460] flags: 0x4; PT_GNU_RELRO
200
201   Program source
202
203       #define _GNU_SOURCE
204       #include <link.h>
205       #include <stdint.h>
206       #include <stdio.h>
207       #include <stdlib.h>
208
209       static int
210       callback(struct dl_phdr_info *info, size_t size, void *data)
211       {
212           char *type;
213           int p_type;
214
215           printf("Name: \"%s\" (%d segments)\n", info->dlpi_name,
216                  info->dlpi_phnum);
217
218           for (size_t j = 0; j < info->dlpi_phnum; j++) {
219               p_type = info->dlpi_phdr[j].p_type;
220               type = (p_type == PT_LOAD) ? "PT_LOAD" :
221                      (p_type == PT_DYNAMIC) ? "PT_DYNAMIC" :
222                      (p_type == PT_INTERP) ? "PT_INTERP" :
223                      (p_type == PT_NOTE) ? "PT_NOTE" :
224                      (p_type == PT_INTERP) ? "PT_INTERP" :
225                      (p_type == PT_PHDR) ? "PT_PHDR" :
226                      (p_type == PT_TLS) ? "PT_TLS" :
227                      (p_type == PT_GNU_EH_FRAME) ? "PT_GNU_EH_FRAME" :
228                      (p_type == PT_GNU_STACK) ? "PT_GNU_STACK" :
229                      (p_type == PT_GNU_RELRO) ? "PT_GNU_RELRO" : NULL;
230
231               printf("    %2zu: [%14p; memsz:%7jx] flags: %#jx; ", j,
232                      (void *) (info->dlpi_addr + info->dlpi_phdr[j].p_vaddr),
233                      (uintmax_t) info->dlpi_phdr[j].p_memsz,
234                      (uintmax_t) info->dlpi_phdr[j].p_flags);
235               if (type != NULL)
236                   printf("%s\n", type);
237               else
238                   printf("[other (%#x)]\n", p_type);
239           }
240
241           return 0;
242       }
243
244       int
245       main(void)
246       {
247           dl_iterate_phdr(callback, NULL);
248
249           exit(EXIT_SUCCESS);
250       }
251

SEE ALSO

253       ldd(1), objdump(1), readelf(1), dladdr(3), dlopen(3), elf(5), ld.so(8)
254
255       Executable and Linking Format Specification, available at various loca‐
256       tions online.
257
258
259
260Linux man-pages 6.05              2023-07-20                dl_iterate_phdr(3)
Impressum