Provided by: manpages-fr-dev_3.27fr1.4-1_all bug

NOM

       backtrace,    backtrace_symbols,    backtrace_symbols_fd    -    Outils
       d'auto-debogage 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);

DESCRIPTION

       backtrace() renvoie une trace des appels du programme dans  un  tableau
       pointe  par  buffer.  Une  trace  est  une  serie  d'appels de fonction
       actuellement actif d'un programme. Chaque element du tableau pointe par
       buffer  est  de  type void *, et correspond a l'adresse de retour de la
       << stack frame >> correspondante. Le parametre size specifie le  nombre
       maximum  d'adresses  qui  peut etre enregistre dans buffer. Si la trace
       est plus grande que size, alors les  adresses  correspondant  aux  size
       plus recents appels de fonction sont retournees. Pour obtenir une trace
       complete, soyez sure que buffer et size sont assez grand.

       A partir  des  adresses  renvoyees  par  backtrace()  dans  le  buffer,
       backtrace_symbols()  traduit  les adresses en un tableau de chaines qui
       donne les symboles associes a ces adresses. Le parametre  size  indique
       le  nombre  d'adresses  dans le buffer. La representation symbolique de
       chaque  adresse  consiste  en  un  nom  de  fonction  (s'il  peut  etre
       determine),  un  decalage  hexadecimal a l'interieur de la fonction, et
       l'adresse (hexadecimale) de retour. L'adresse du tableau de chaines est
       renvoye  comme  resultat de la fonction backtrace_symbols(). Ce tableau
       est alloue avec malloc(3) par backtrace_symbols() et doit  etre  libere
       par  l'appelant. Les chaines pointees par le tableau de pointeurs n'ont
       pas et ne devraient pas etre liberees.

       backtrace_symbols_fd() prend les memes parametres buffer  et  size  que
       backtrace_symbols()  mais  au  lieu de renvoyer un tableau de chaines a
       l'appelant, elle ecrit les chaines ligne par ligne dans le  descripteur
       de  fichier  fd. backtrace_symbols_fd() n'appelle pas malloc(3) et peut
       donc etre utilisee dans  des  conditions  ou  cette  derniere  fonction
       risque d'echouer.

VALEUR RENVOY'EE

       backtrace()  fournit le nombre d'adresses renvoyees dans le buffer, qui
       ne sera pas superieur a size. Si la valeur de retour est  inferieure  a
       size, alors toute la trace a pu etre sauvee ; si elle est egale a size,
       alors il se peut qu'elle ait ete tronquee et les  adresses  des  trames
       les plus anciennes sur la pile ne sont pas renvoyees.

       En  cas  de  succes,  backtrace_symbols()  renvoie  un pointeur vers le
       tableau alloue avec malloc(3). En cas d'erreur NULL est renvoye.

VERSIONS

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

CONFORMIT'E

       Ces fonctions sont des extensions GNU.

NOTES

       Ces  fonctions  font  des  suppositions  sur la facon dont l'adresse de
       retour d'une fonction est sauvegardee dans la  pile.  Prenez  note  des
       points suivants :

       *  L'omission  du  pointeur  de  trame  (comme  le fait gcc(1) avec les
          niveaux d'optimisation differents de zero)  peut  etre  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
          etre remplacee par une autre.

       Le nom des symboles peut ne pas etre disponible si certaines options de
       l'editeur de liens n'ont pas  ete  utilisees.  Pour  les  systemes  qui
       utilisent  l'editeur de liens GNU, il faut utiliser l'option -rdynamic.
       Notez  que  les  noms  des  fonctions  statiques  (avec  le  mot   clef
       << static >>) ne sont pas exposes, et ne seront pas disponibles pour la
       trace.

EXEMPLE

       Le  programme  ci-dessous  explique  l'utilisation  de  backtrace()  et
       backtrace_symbols().  Les sessions d'interpreteur de commandes montrent
       ce que produira l'execution 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.27  du  projet  man-pages
       Linux.  Une description du projet et des instructions pour signaler des
       anomalies      peuvent      etre       trouvees       a       l'adresse
       <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION

       Depuis  2010,  cette  traduction est maintenue a l'aide de l'outil po4a
       <URL:http://po4a.alioth.debian.org/>   par   l'equipe   de   traduction
       francophone        au        sein        du       projet       perkamon
       <URL:http://perkamon.alioth.debian.org/>.

       Florentin   Duneau   et   l'equipe   francophone   de   traduction   de
       Debian (2006-2009).

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

       Vous  pouvez  toujours avoir acces a la version anglaise de ce document
       en utilisant la commande << man -L C <section> <page_de_man> >>.