Loading

NOM

       backtrace,    backtrace_symbols,    backtrace_symbols_fd    -    Outils
       d’auto-débogage d’applications

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);

       backtrace() renvoie une trace des appels du programme dans  un  tableau
       pointé  par  buffer.  Une  trace  est  une  série  d’appels de fonction
       actuellement actif d’un programme. Chaque élément du tableau pointé par
       buffer  est  de  type void *, et correspond à l’adresse de retour de la
       « stack frame » correspondante. Le paramètre size  spécifie  le  nombre
       maximum  d’adresses  qui  peut être enregistré dans buffer. Si la trace
       est plus grande que size, alors les  adresses  correspondant  aux  size
       plus récents appels de fonction sont retournées. Pour obtenir une trace
       complète, soyez sûre que buffer et size sont assez grand.

       À partir  des  adresses  renvoyées  par  backtrace()  dans  le  buffer,
       backtrace_symbols()  traduit  les adresses en un tableau de chaînes qui
       donne les symboles associés à ces adresses. Le paramètre  size  indique
       le  nombre  d’adresses  dans le buffer. La représentation symbolique de
       chaque  adresse  consiste  en  un  nom  de  fonction  (s’il  peut  être
       déterminé),  un  décalage  hexadécimal à l’intérieur de la fonction, et
       l’adresse (hexadécimale) de retour. L’adresse du tableau de chaînes est
       renvoyé  comme  résultat de la fonction backtrace_symbols(). Ce tableau
       est alloué avec malloc(3) par backtrace_symbols() et doit  être  libéré
       par  l’appelant. Les chaînes pointées par le tableau de pointeurs n’ont
       pas et ne devraient pas être libérées.

       backtrace_symbols_fd() prend les mêmes paramètres buffer  et  size  que
       backtrace_symbols()  mais  au  lieu de renvoyer un tableau de chaînes à
       l’appelant, elle écrit les chaînes ligne par ligne dans le  descripteur
       de  fichier  fd. backtrace_symbols_fd() n’appelle pas malloc(3) et peut
       donc être utilisée dans  des  conditions  où  cette  dernière  fonction
       risque d’échouer.

VALEUR RENVOYÉE

       backtrace()  fournit le nombre d’adresses renvoyées dans le buffer, qui
       ne sera pas supérieur à size. Si la valeur de retour est  inférieure  à
       size, alors toute la trace a pu être sauvée ; si elle est égale à size,
       alors il se peut qu’elle ait été tronquée et les  adresses  des  trames
       les plus anciennes sur la pile ne sont pas renvoyées.

       En  cas  de  succès,  backtrace_symbols()  renvoie  un pointeur vers le
       tableau alloué avec malloc(3). En cas d’erreur NULL est renvoyé.

VERSIONS

       backtrace(),   backtrace_symbols()   et   backtrace_symbols_fd()   sont
       fournies par la glibc depuis la version 2.1.

CONFORMITÉ

       Ces fonctions sont des extensions GNU.

NOTES

       Ces  fonctions  font  des  suppositions  sur la façon dont l’adresse de
       retour d’une fonction est sauvegardée dans la  pile.  Prenez  note  des
       points suivants :

       *  L’omission  du  pointeur  de  trame  (comme  le fait gcc(1) avec les
          niveaux d’optimisation différents de zéro)  peut  être  incompatible
          avec ces suppositions.

       *  Les fonctions en lignes (« inline ») n’apparaissent pas sur la pile.

       *  Avec les optimisations de type Tail-call une trame sur la pile  peut
          être remplacée par une autre.

       Le nom des symboles peut ne pas être disponible si certaines options de
       l’éditeur de liens n’ont pas  été  utilisées.  Pour  les  systèmes  qui
       utilisent  l’éditeur de liens GNU, il faut utiliser l’option -rdynamic.
       Notez  que  les  noms  des  fonctions  statiques  (avec  le  mot   clef
       « static »)  ne  sont pas exposés, et ne seront pas disponibles pour la
       trace.

EXEMPLE

       Le  programme  ci-dessous  explique  l’utilisation  de  backtrace()  et
       backtrace_symbols().  Les sessions d’interpréteur de commandes montrent
       ce que produira 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]

   Source du programme

       #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)

COLOPHON

       Cette page fait partie de  la  publication  3.23  du  projet  man-pages
       Linux.  Une description du projet et des instructions pour signaler des
       anomalies      peuvent      être       trouvées       à       l’adresse
       http://www.kernel.org/doc/man-pages/.

TRADUCTION

       Cette  page  de  manuel  a  été traduite et est maintenue par Florentin
       Duneau <fduneau AT gmail DOT com> et l’équipe francophone de traduction
       de Debian.

       Veuillez   signaler   toute   erreur   de   traduction  en  écrivant  à
       <debian-l10n-french@lists.debian.org> ou par un rapport de bogue sur le
       paquet manpages-fr.

       Vous  pouvez  toujours avoir accès à la version anglaise de ce document
       en utilisant la commande « man -L C <section> <page_de_man> ».