man3/dl_iterate_phdr.3

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