dl_iterate_phdr

Synopsis

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 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.

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:

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.

See Also

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.