Standard C Library Functions dl_iterate_phdr(3C)
NAME
dl_iterate_phdr - walk through a list of objects
SYNOPSIS
#include
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 beenprocessed 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 toby info; and the data argument passed to dl_iterate_phdr()
by the caller.The info argument is a pointer to a structure of the follow-
ing 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.
SunOS 5.11 Last change: 22 Feb 2010 1
Standard C Library Functions dl_iterate_phdr(3C)
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 other-
wise. 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, anddlpi_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
#include
#include
static intcallback(struct dl_phdr_info *info, size_t size, void *data)
{ int j;SunOS 5.11 Last change: 22 Feb 2010 2
Standard C Library Functions dl_iterate_phdr(3C)
printf("name=%s (%d program headers)0, info->dlpi_name,
info->dlpi_phnum);
for (j = 0; j < info->dlpi_phnum; j++) {
if (info->dlpi_phdr[j].p_type == PT_LOAD)
printf("[%d] 0x%p0, 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 sup-
ply 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 callbackfunction can detect the presence of the dlpi_adds and
dlpi_subs fields described above:
static intcallback(struct dl_phdr_info *info, size_t size, void *data)
{ /** This must match the definition of dl_phdr_info, as
* defined in. 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: %s0, info->dlpi_name);
printf(" addr: 0x%p0, (u_longlong_t) info->dlpi_addr);
SunOS 5.11 Last change: 22 Feb 2010 3
Standard C Library Functions dl_iterate_phdr(3C)
printf(" phdr: 0x%p0, (u_longlong_t) info->dlpi_phdr);
printf(" phnum: %d0, (int) info->dlpi_phnum);
if (size >= sizeof (struct dl_phdr_info_test)) {
printf(" adds: %llu0, info->dlpi_adds);
printf(" subs: %llu0, 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 availableonly to dynamically-linked processes. See the Linker and
Libraries Guide.ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Committed ||_____________________________|_____________________________|
| MT-Level | MT-Safe |
|_____________________________|_____________________________|
SEE ALSO
ld(1), ld.so.1(1), dladdr(3C), dlclose(3C), dldump(3C),dlerror(3C), dlinfo(3C), dlopen(3C), dlsym(3C), attri-
butes(5), standards(5) Linker and Libraries Guide NOTESdl_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 orSunOS 5.11 Last change: 22 Feb 2010 4
Standard C Library Functions dl_iterate_phdr(3C)
a call to dlopen(), is undefined. The call todl_iterate_phdr() that triggers the load may or may not
issue a callback for the new object. This depends on thecurrent 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 func-
tion, 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 changedbetween the two calls. An application can use this informa-
tion to cache object data, and avoid unnecessary iteration. In such a scenario, the first call to the callback functionwould 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.SunOS 5.11 Last change: 22 Feb 2010 5