Provided by: manpages-fr-dev_3.32d0.2p4-1_all bug

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

DESCRIPTION

       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.32 du projet man-pages Linux. Une description
       du projet et des  instructions  pour  signaler  des  anomalies  peuvent  être  trouvées  à
       l'adresse <URL:http://www.kernel.org/doc/man-pages/>.

TRADUCTION

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

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

       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> ».