dl_iterate_phdr

Description

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.

dlpi_adds and dlpi_subs are incremented when shared objects are added or removed, respectively.

dlpi_tls_modid contains the module ID used in TLS relocations, if there is a PT_TLS segment. Otherwise the value shall be zero.

dlpi_tls_data contains the address of the calling thread's instance of this module's PT_TLS segment, 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.

Return Value

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.

Errors

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.