DL_ITERATE_PHDR(3)        Linux Programmer's Manual       DL_ITERATE_PHDR(3)

NAME         top

       dl_iterate_phdr - walk through list of shared objects

SYNOPSIS         top

       #define _GNU_SOURCE         /* See feature_test_macros(7) */
       #include <link.h>

       int dl_iterate_phdr(
                 int (*callback) (struct dl_phdr_info *info,
                                  size_t size, void *data),
                 void *data);

DESCRIPTION         top

       The dl_iterate_phdr() function allows an application to inquire at
       run time to find out which shared objects it has loaded.

       The dl_iterate_phdr() function walks through the list of an
       application's shared objects and calls the function callback once for
       each object, until either all shared objects have been processed or
       callback returns a nonzero value.

       Each call to callback receives three arguments: info, which is a
       pointer to a structure containing information about the shared
       object; size, which is the size of the structure pointed to by info;
       and data, which is a copy of whatever value was passed by the calling
       program as the second argument (also named data) in the call to

       The info argument is a structure of the following type:

           struct dl_phdr_info {
               ElfW(Addr)        dlpi_addr;  /* Base address of object */
               const char       *dlpi_name;  /* (Null-terminated) name of
                                                object */
               const ElfW(Phdr) *dlpi_phdr;  /* Pointer to array of
                                                ELF program headers
                                                for this object */
               ElfW(Half)        dlpi_phnum; /* # of items in dlpi_phdr */

               /* The following fields were added in glibc 2.4, after the first
                  version of this structure was available.  Check the size
                  argument passed to the dl_iterate_phdr callback to determine
                  whether or not each later member is available.  */

               unsigned long long int dlpi_adds;
                               /* Incremented when a new object may
                                  have been added */
               unsigned long long int dlpi_subs;
                               /* Incremented when an object may
                                  have been removed */
               size_t dlpi_tls_modid;
                               /* If there is a PT_TLS segment, its module
                                  ID as used in TLS relocations, else zero */
               void  *dlpi_tls_data;
                               /* The address of the calling thread's instance
                                  of this module's PT_TLS segment, if it has
                                  one and it has been allocated in the calling
                            thread, otherwise a null pointer */

       (The ElfW() macro definition turns its argument into the name of an
       ELF data type suitable for the hardware architecture.  For example,
       on a 32-bit platform, ElfW(Addr) yields the data type name
       Elf32_Addr.  Further information on these types can be found in the
       <elf.h> and <link.h> header files.)

       The dlpi_addr field indicates the base address of the shared object
       (i.e., the difference between the virtual memory address of the
       shared object and the offset of that object in the file from which it
       was loaded).  The dlpi_name field is a null-terminated string giving
       the pathname from which the shared object was loaded.

       To understand the meaning of the dlpi_phdr and dlpi_phnum fields, we
       need to be aware that an ELF shared object consists of a number of
       segments, each of which has a corresponding program header describing
       the segment.  The dlpi_phdr field is a pointer to an array of the
       program headers for this shared object.  The dlpi_phnum field
       indicates the size of this array.

       These program headers are structures of the following form:

           typedef struct {
               Elf32_Word  p_type;    /* Segment type */
               Elf32_Off   p_offset;  /* Segment file offset */
               Elf32_Addr  p_vaddr;   /* Segment virtual address */
               Elf32_Addr  p_paddr;   /* Segment physical address */
               Elf32_Word  p_filesz;  /* Segment size in file */
               Elf32_Word  p_memsz;   /* Segment size in memory */
               Elf32_Word  p_flags;   /* Segment flags */
               Elf32_Word  p_align;   /* Segment alignment */
           } Elf32_Phdr;

       Note that we can calculate the location of a particular program
       header, x, in virtual memory using the formula:

         addr == info->dlpi_addr + info->dlpi_phdr[x].p_vaddr;

RETURN VALUE         top

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

VERSIONS         top

       dl_iterate_phdr() has been supported in glibc since version 2.2.4.

ATTRIBUTES         top

       For an explanation of the terms used in this section, see

       │Interface         Attribute     Value   │
       │dl_iterate_phdr() │ Thread safety │ MT-Safe │

CONFORMING TO         top

       The dl_iterate_phdr() function is not specified in any standard.
       Various other systems provide a version of this function, although
       details of the returned dl_phdr_info structure differ.  On the BSDs
       and Solaris, the structure includes the fields dlpi_addr, dlpi_name,
       dlpi_phdr, and dlpi_phnum in addition to other implementation-
       specific fields.

NOTES         top

       Future versions of the C library may add further fields to the
       dl_phdr_info structure; in that event, the size argument provides a
       mechanism for the callback function to discover whether it is running
       on a system with added fields.

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

EXAMPLE         top

       The following program displays a list of pathnames of the shared
       objects it has loaded.  For each shared object, the program lists the
       virtual addresses at which the object's ELF segments are loaded.

       #define _GNU_SOURCE
       #include <link.h>
       #include <stdlib.h>
       #include <stdio.h>

       static int
       callback(struct dl_phdr_info *info, size_t size, void *data)
           int j;

           printf("name=%s (%d segments)\n", info->dlpi_name,

           for (j = 0; j < info->dlpi_phnum; j++)
                printf("\t\t header %2d: address=%10p\n", j,
                    (void *) (info->dlpi_addr + info->dlpi_phdr[j].p_vaddr));
           return 0;

       main(int argc, char *argv[])
           dl_iterate_phdr(callback, NULL);


SEE ALSO         top

       ldd(1), objdump(1), readelf(1), dladdr(3), dlopen(3), elf(5),

       Executable and Linking Format Specification, available at various
       locations online.

COLOPHON         top

       This page is part of release 4.10 of the Linux man-pages project.  A
       description of the project, information about reporting bugs, and the
       latest version of this page, can be found at

GNU                              2016-03-15               DL_ITERATE_PHDR(3)