dl_iterate_phdr() allows a program to iterate over the shared objects it has loaded. The function described by the callback parameter is called once for each loaded shared object, allowing an action to be taken for each one. callback is called with three arguments which are filled in by the implementation: a pointer to a structure of type dl_phdr_info containing information about the shared object; an integer size of the structure; and a copy of the data argument to dl_iterate_phdr(). If callback returns a non-zero value, dl_iterate_phdr() will stop processing, even if there are unprocessed shared objects. The order of processing is unspecified.
The dl_phdr_info structure has the following members (note that on 64-bit architectures the types here shown as Elf32_type will instead be Elf64_type):
Elf32_Addr dlpi_addr; const char *dlpi_name; const Elf32_Phdr *dlpi_phdr; Elf32_Half dlpi_phnum; unsigned long long int dlpi_adds; unsigned long long int dlpi_subs; size_t dlpi_tls_modid; void *dlpi_tls_data;
dlpi_addr contains the base address
of the shared object.
dlpi_name is a null-terminated string
giving the pathname from which the shared object was loaded.
dlpi_phdr is a pointer to an array
of program headers for this shared object, while
dlpi_phnum is the number of
entries in this array.
incremented when shared objects are added or removed, respectively.
contains the module ID used in TLS relocations,
if there is a
Otherwise the value shall be zero.
contains the address of the calling thread's instance
of this module's
if there is one and it has been allocated in the calling thread.
Otherwise the value shall be a null pointer.
Some implementations may not provide all fields in dl_phdr_info, although the first four are always mandatory. Applications are advised to have the callback function check the size parameter before examining the later members.
The dl_iterate_phdr() function returns whatever value was returned by the last call to callback. This will be zero if processing completed normally, since processing does not continue unless the callback function returns zero.
No errors are defined by dl_iterate_phdr(); as noted the callback function must use a zero return to indicate success but may assign any meaning it wishes to non-zero returns.