BACKTRACE(3)

NOM
backtrace, backtrace_symbols, backtrace_symbols_fd - Support pour l'autodégogage d'application

SYNOPSIS
#include <execinfo.h> int backtrace(void **buffer, int size); char **backtrace_symbols(void *const *buffer, int size); void backtrace_symbols_fd(void *const *buffer, int size, int fd);

DESCRIPTION
backtrace() renvoie une trace inverse des appels du programme dans un tableau pointé par buffer. Une trace inverse est la série d'appels de fonctions du programme actuellement actives. Chaque élément du tableau pointé par buffer est de type void *, et est l'adresse de retour du cadre de la pile (Ndt : « stack frame ») correspondant. L'argument size indique le nombre maximum d'adresses qui peuvent être stockées dans buffer. Si la trace inverse est plus grande que size, les adresses correspondant aux size plus récents appels de fonctions sont retournés ; pour obtenir une trace complète, assurez-vous que buffer et size soient assez grands. En lui fournissant l'ensemble des adresses retournées par backtrace() dans buffer, backtrace_symbols() traduit les adresses dans un tableau de chaînes qui décrivent symboliquement les adresses. L'argument size indique le nombre d'adresses dans buffer. La représentation symbolique de chaque adresse consiste en le nom de la fonction (s'il peut être déterminé), un décalage hexadécimal dans la fonction et l'adresse courante de retour (en hexadécimal). L'adresse du tableau des pointeurs de chaînes est renvoyé comme le résultat de la fonction backtrace_symbols(). Le tableau est alloué avec malloc(3) par backtrace_symbols(), et doit donc être libéré (free(3)) par l'appelant. (Les chaînes pointées par strings n'ont pas besoin (et ne doivent pas) d'être libérées.) backtrace_symbols_fd() prend les mêmes arguments buffer et size que backtrace_symbols(), plutôt que de retourner un tableau de chaînes à l'appelant, elle remplit les chaînes, une par ligne, dans le descripteur de fichier fd. backtrace_symbols() n'appelle pas malloc(3), et peut donc être utilisée dans des situations où la dernière fonction peut échouer.

VALEUR RENVOYÉE
backtrace() renvoie le nombre d'adresses retournées dans buffer, qui n'est pas plus grand que size. Si la valeur de retour est inférieure à size, la trace complète est stockée ; si elle est égale à size, la trace peut être tronquée, auquel cas les adresses des plus anciens cadres de piles ne sont pas retournés. Si elle réussit, backtrace_symbols() renvoie un pointer sur le tableau alloué avec malloc(3) par l'appel ; si elle échoue, elle renvoie NULL.

CONFORMITÉ
Ces fonctions sont des extensions GNU.

NOTES
Ces fonctions font certaines suppositions sur la façon dont l'adresse de retour d'une fonction est stockée dans la pile. Veuillez noter ce qui suit :

*   L'omission des pointeurs de cadres (comme impliqué par n'importe quel niveau d'optimisation non nul de gcc(1)) peut provoquer la violation de ces suppositions.

*   Les fonctions intégrées n'ont pas de cadres de pile.

*   L'optimisation de point d'appel provoque le remplacement d'un cadre de pile par un autre.

Les noms de symboles peuvent ne pas être disponibles sans l'utilisation d'options particulières de l'éditeur de liens. Pour les systèmes qui utilisent l'éditeur de liens GNU, il faut utiliser l'option -rdynamic de l'éditeur de liens. Veuillez noter que les noms des fonctions « static » ne sont pas exposés et ne seront pas disponibles dans la trace.

EXEMPLE
Le programme suivant montre l'utilisation de backtrace() et backtrace_symbols(). La session shell suivante montre ce que nous pourrions voir lors de l'exécution du programme :
 $ cc -rdynamic prog.c -o prog
 $ ./prog 3
 backtrace() returned 8 addresses
 ./prog(myfunc3+0x5c) [0x80487f0]
 ./prog [0x8048871]
 ./prog(myfunc+0x21) [0x8048894]
 ./prog(myfunc+0x1a) [0x804888d]
 ./prog(myfunc+0x1a) [0x804888d]
 ./prog(main+0x65) [0x80488fb]
 /lib/libc.so.6(__libc_start_main+0xdc) [0xb7e38f9c]
 ./prog [0x8048711]
#include <execinfo.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
void
myfunc3(void)
{
    int j, nptrs;
#define SIZE 100
    void *buffer[100];
    char **strings;
    nptrs = backtrace(buffer, SIZE);
    printf("backtrace() returned %d addresses\n", nptrs);
    /* The call backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO)
       would produce similar output to the following: */
    strings = backtrace_symbols(buffer, nptrs);
    if (strings == NULL) {
        perror("backtrace_symbols");
        exit(EXIT_FAILURE);
    }
    for (j = 0; j < nptrs; j++)
        printf("%s\n", strings[j]);
    free(strings);
}
static void   /* 'static' means don't export the symbol... */
myfunc2(void)
{
    myfunc3();
}
void
myfunc(int ncalls)
{
    if (ncalls > 1)
        myfunc(ncalls - 1);
    else
        myfunc2();
}
int
main(int argc, char *argv[])
{
    if (argc != 2) {
        fprintf(stderr, "%s num-calls\n", argv[0]);
        exit(EXIT_FAILURE);
    }
    myfunc(atoi(argv[1]));
    exit(EXIT_SUCCESS);
}

VOIR AUSSI
gcc(1), ld(1), dlopen(3), malloc(3)

TRADUCTION

Ce document est une traduction réalisée par Alain Portal <aportal AT univ-montp2 DOT fr> le 13 décembre 2007 et révisée le 22 décembre 2007.

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 backtrace ». N'hésitez pas à signaler à l'auteur ou au traducteur, selon le cas, toute erreur dans cette page de manuel.