DL_ITERATE_PHDR(3)

NOM
dl_iterate_phdr - Parcourir dans une liste d'objets partagés

SYNOPSIS
#define _GNU_SOURCE
#include <link.h>
int dl_iterate_phdr(
          int (*callback) (struct dl_phdr_info *info,
                           size_t size, void *data),
          void *data);

DESCRIPTION
La fonction dl_iterate_phdr() permet à une application de s'enquérir, pendant son exécution, des objets partagés qu'elle a chargée. La fonction dl_iterate_phdr() parcourt la liste des objets partagés d'une application et appelle la fonction callback une fois pour chaque objet, jusqu'à ce que soit tous les objets partagés aient été traités, soit la fonction callback ait retournée une valeur non nulle. Chaque appel à callback prend trois arguments : info, qui est un pointeur vers une structure contenant des informations relatives à l'objet partagé ; size, qui est la taille de la structure pointée par info ; et data, qui est une copie de toute valeur passée par le programme appelant comme second argument (également nommé data) dans l'appel à dl_iterate_phdr(). L'argument info est une structure de type suivant :
struct dl_phdr_info {
    ElfW(Addr)        dlpi_addr;  /* Adresse de base de l'objet */
    const char       *dlpi_name;  /* Nom de l'objet (terminé par
                                     un octet nul) */
    const ElfW(Phdr) *dlpi_phdr;  /* Pointeur sur le tableau des
                                     entêtes programme ELF
                                     pour cet objet */
    ElfW(Half)        dlpi_phnum; /* Nombre d'éléments dans dlpi_phdr */
};
(La définition de la macro ElfW() transforme son argument en un nom de type de données ELF compréhensible par l'architecture matérielle. Par exemple, sur une plate-forme 32 bits, ElfW(Addr) produit le nom de type de données Elf32_Addr. Vous pourrez trouver plus d'informations sur ces types dans les fichiers d'entêtes <elf.h> et <link.h>). Le champ dlpi_addr indique l'adresse de base de l'objet partagé (c'est-à-dire, la différence entre l'adresse en mémoire virtuelle de l'objet partagé et le décalage de cet objet dans le fichier à partir duquel il a été chargé). Le champ dlpi_name est une chaîne de caractère terminée par un octet nul donnant le chemin à partir duquel l'objet partagé a été chargé. Pour comprendre la signification des champs dlpi_phdr et dlpi_phnum, nous devons avoir conscience qu'un objet partagé ELF consiste en un nombre de segments, chacun de ceux-ci ayant un entête programme le décrivant. Le champ dlpi_phdr est un pointeur vers un tableau des entêtes programme de cet objet partagé. Le champ dlpi_phnum indique la taille de ce tableau. Ces entêtes de programme sont des structures de la forme suivante :
typedef struct {
    Elf32_Word  p_type;    /* Type du segment */
    Elf32_Off   p_offset;  /* Décalage fichier du segment */
    Elf32_Addr  p_vaddr;   /* Adresse virtuelle du segment */
    Elf32_Addr  p_paddr;   /* Adresse physique du segment */
    Elf32_Word  p_filesz;  /* Taille du segment dans le fichier */
    Elf32_Word  p_memsz;   /* Taille du segment en mémoire */
    Elf32_Word  p_flags;   /* Attributs du segment */
    Elf32_Word  p_align;   /* Alignement du segment */
} Elf32_Phdr;
Veuillez noter que l'on peut calculer l'endroit où se situe un entête programme particulier x en mémoire virtuelle en utilisant la formule :
  addr == info->dlpi_addr + info->dlpi_phdr[x].p_vaddr;

VALEUR RENVOYÉE
La fonction dl_iterate_phdr() renvoie toute valeur qui a été retournée par le dernier appel à callback.

VERSIONS
dl_iterate_phdr() est prise en charge dans la glibc depuis la version 2.2.4.

CONFORMITÉ
La fonction dl_iterate_phdr() est spécifique à Linux et ne devrait pas être utilisée dans des applications destinées à être portables.

EXEMPLE
Le programme suivant affiche la liste des chemins des objets partagés qu'il a chargé. Pour chaque objet partagé, le programme affiche les adresses virtuelles auxquelles les segments ELF de l'objet sont chargés.
#define _GNU_SOURCE
#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 segments)\n", info->dlpi_name,
        info->dlpi_phnum);
    for (j = 0; j < info->dlpi_phnum; j++)
         printf("\t\t header %2d: address=%10p\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);
    exit(EXIT_SUCCESS);
}

VOIR AUSSI
ldd(1), objdump(1), readelf(1), dlopen(3), feature_test_macros(7), ld.so(8), et la Executable and Linking Format Specification disponible dans divers endroits en ligne (Ndt : elf(5)).

TRADUCTION

Ce document est une traduction réalisée par Alain Portal <aportal AT univ-montp2 DOT fr> le 12 mai 2006 et révisée le 17 juillet 2008.

L'équipe de traduction a fait le maximum pour réaliser une adaptation française de qualité. La version anglaise la plus à jour de ce document est toujours consultable via la commande : « LANG=C man 3 dl_iterate_phdr ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.