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

NAME
       dliteratephdr - walk through list of shared objects

SYNOPSIS
       #define GNUSOURCE         /* See featuretestmacros(7) */
       #include 

       int dliteratephdr(
                 int (*callback) (struct dlphdrinfo *info,
                                  sizet size, void *data,
                 void *data;

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

       The dliteratephdr() function walks through the list  of  an  applica‐
       tion'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 dliteratephdr().

       The info argument is a structure of the following type:

           struct dlphdrinfo {
               ElfW(Addr)        dlpiaddr;  /* Base address of object */
               const char       *dlpiname;  /* (Null-terminated) name of
                                                object */
               const ElfW(Phdr) *dlpiphdr;  /* Pointer to array of
                                                ELF program headers
                                                for this object */
               ElfW(Half)        dlpiphnum; /* # of items in dlpiphdr */
           };

       (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 Elf32Addr.  Fur‐
       ther information on these  types  can  be  found  in  the    and
        header files.)

       The  dlpiaddr  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 dlpiname field is a null-terminated  string  giving  the
       pathname from which the shared object was loaded.

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

       These program headers are structures of the following form:

           typedef struct {
               Elf32Word  ptype;    /* Segment type */
               Elf32Off   poffset;  /* Segment file offset */
               Elf32Addr  pvaddr;   /* Segment virtual address */
               Elf32Addr  ppaddr;   /* Segment physical address */
               Elf32Word  pfilesz;  /* Segment size in file */
               Elf32Word  pmemsz;   /* Segment size in memory */
               Elf32Word  pflags;   /* Segment flags */
               Elf32Word  palign;   /* Segment alignment */
           } Elf32Phdr;

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

         addr == info->dlpiaddr + info->dlpiphdr[x].pvaddr;

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

VERSIONS
       dliteratephdr() has been supported in glibc since version 2.2.4.

CONFORMING TO
       The dliteratephdr() function is Linux-specific and should be  avoided
       in portable applications.

EXAMPLE
       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 GNUSOURCE
       #include 
       #include 
       #include 

       static int
       callback(struct dlphdrinfo *info, sizet size, void *data)
       {
           int j;

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

           for (j = 0; j < info->dlpiphnum; j++)
                printf("\t\t header %2d: address=%10p\n", j,
                    (void *) (info->dlpiaddr + info->dlpiphdr[j].pvaddr));
           return 0;
       }

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

           exit(EXITSUCCESS);
       }

SEE ALSO
       ldd(1), objdump(1), readelf(1), dlopen(3), elf(5), ld.so(8)

       Executable and Linking Format Specification, available at various loca‐
       tions online.

COLOPHON
       This page is part of release 3.53 of the Linux  man-pages  project.   A
       description  of  the project, and information about reporting bugs, can
       be found at http://www.kernel.org/doc/man-pages/.



GNU                               2007-05-18                DLITERATEPHDR(3)