dl_iterate_phdr

- walk through a list of objects

Synopsis

#include <link.h>

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

Description

The dl_iterate_phdr() function returns information regarding each ELF object currently resident in the process address space.

The dl_iterate_phdr() function calls the function callback once for each object, until either all objects have been processed or callback returns a non-zero value.

Each call to callback receives three arguments: info, which is a pointer to a structure containing information about the object; size, which is the size of the structure pointed to by info; and the data argument passed to dl_iterate_phdr() by the caller.

The info argument is a pointer to a structure of the following type:

     struct dl_phdr_info {
             /* Fields present in all implementations */
             ElfW(Addr)       dlpi_addr;
             const char       *dlpi_name;
             const ElfW(Phdr) *dlpi_phdr;
             ElfW(Half)       dlpi_phnum;

             /* Additional fields present in this implementation */
             u_longlong_t     dlpi_adds;
             u_longlong_t     dlpi_subs;
     };

The ElfW() macro definition turns its argument into the name of an ELF data type suitable for the hardware architecture, by adding the Elf32_ prefix for 32-bit code, or Elf64_ for 64-bit code.

The first four fields (dlpi_addr, dlpi_name, dlpi_phdr, dlpi_phnum) are present in all implementations of dl_iterate_phdr(), and can be accessed on any system that provides this function. The callback function must use the size argument to determine if the remaining fields (dlpi_adds, dlpi_subs) are present. See EXAMPLES.

The dlpi_addr field is 0 for executable objects (ET_EXEC), and is the base address at which the object is mapped otherwise. Therefore, the address of any loadable segment in the program header array can be calculated as:

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

dlpi_name gives the pathname of the object.

dlpi_phdr provides a pointer to the program header array for the object, and dlpi_phnum specifies the number of program headers found in the array.

dlpi_adds provides the number of objects that have been mapped into the current process since it started, and dlpi_subs provides the number of objects that have been unmapped. See NOTES.

See the Linker and Libraries Guide for more information about ELF objects, and the information contained in program headers.

Examples

Example 1 Display all currently mapped object

The following program displays the pathnames of currently mapped objects. For each object, the virtual address of each loadable segment is shown.

     #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 program headers)\n", info->dlpi_name,
                 info->dlpi_phnum);
             for (j = 0; j < info->dlpi_phnum; j++) {
                     if (info->dlpi_phdr[j].p_type == PT_LOAD)
                             printf("\t[%d] 0x%p\n", j,
                                 (void *) (info->dlpi_addr +
                                 info->dlpi_phdr[j].p_vaddr));
             }
             return 0;
     }

     int
     main(int argc, char *argv[])
     {
             dl_iterate_phdr(callback, NULL);
             return(0);
     }

Example 2 Testing for optional dl_phdr_info fields

Every implementation of dl_iterate_phdr is required to supply the first four fields in struct dl_phdr_info described above. The callback is allowed to assume that they are present and to access them without first testing for their presence. Additional fields may be present. The callback must use the size argument to test for their presence before accessing them. This example demonstrates how a callback function can detect the presence of the dlpi_adds and dlpi_subs fields described above:

     static int
     callback(struct dl_phdr_info *info, size_t size, void *data)
     {
             /*
              * This must match the definition of dl_phdr_info, as
              * defined in <link.h>. It is used to determine whether
              * the info structure contains optional fields.
              */
             struct dl_phdr_info_test {
                     ElfW(Addr)              dlpi_addr;
                     const char              *dlpi_name;
                     const ElfW(Phdr)        *dlpi_phdr;
                     ElfW(Half)              dlpi_phnum;
                     u_longlong_t            dlpi_adds;
                     u_longlong_t            dlpi_subs;
             };
     
             printf("object:  %s\n", info->dlpi_name);
             printf("    addr:  0x%p\n", (u_longlong_t) info->dlpi_addr);
             printf("    phdr:  0x%p\n", (u_longlong_t) info->dlpi_phdr);
             printf("    phnum: %d\n", (int) info->dlpi_phnum);
             if (size >= sizeof (struct dl_phdr_info_test)) {
                     printf("    adds:  %llu\n", info->dlpi_adds);
                     printf("    subs:  %llu\n", info->dlpi_subs);
             }
             return (0);
     }

Return Values

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

Usage

The dl_iterate_phdr() function is a member of a family of functions that give the user direct access to the dynamic linking facilities. This family of functions is available only to dynamically-linked processes. See the Linker and Libraries Guide.

Attributes

See attributes(5) for descriptions of the following attributes:

See Also

ld(1), ld.so.1(1), dladdr(3C), dlclose(3C), dldump(3C), dlerror(3C), dlinfo(3C), dlopen(3C), dlsym(3C), attributes(5), standards(5)

Linker and Libraries Guide

Notes

dl_iterate_phdr() was originally defined by the Linux operating system, and is contained in the Linux Standard Base (LSB).

The behavior of dl_iterate_phdr()when a callback function causes a new object to be loaded, either via lazy loading or a call to dlopen(), is undefined. The call to dl_iterate_phdr() that triggers the load may or may not issue a callback for the new object. This depends on the current position of dl_iterate_phdr() in the list of known objects when the new object is added. The caller must make no assumptions about this case.

dl_iterate_phdr() callbacks must not unload objects. If a call to dlclose()is detected from within the callback function, dl_iterate_phdr() immediately terminates the iteration operation and returns a value of -1.

If two separate calls to dl_iterate_phdr() provide the same two values for dlpi_adds and dlpi_subs, the caller may safely assume that the process object state has not changed between the two calls. An application can use this information to cache object data, and avoid unnecessary iteration. In such a scenario, the first call to the callback function would check to see if a cache exists, and that dlpi_adds and dlpi_subs have not changed since the last call to dl_iterate_phdr(), and if so, return a non-zero value to terminate the iteration operation immediately.