Provided by: manpages-fr-dev_4.19.0-7_all bug

NOM

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

BIBLIOTHÈQUE

       Bibliothèque C standard (libc, -lc)

SYNOPSIS

       #include <execinfo.h>

       int backtrace(void *buffer[.size], int size);

       char **backtrace_symbols(void *const buffer[.size], int size);
       void backtrace_symbols_fd(void *const buffer[.size], 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 actifs  d'un  programme.  Chaque
       élément  du  tableau  pointé  par  buffer est de type void *, et correspond à l'adresse de
       retour du bloc de pile (stack frame) correspondant. Le paramètre size spécifie  le  nombre
       maximal  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
       renvoyées.  Pour  obtenir une trace complète, assurez-vous que buffer et size soient assez
       grands.

       À partir des adresses  renvoyées  par  backtrace()  dans  le  buffer,  backtrace_symbols()
       traduit  les adresses en un tableau de chaînes qui associe des symboles à 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 renvoi.  L'adresse
       du   tableau   de  pointeurs  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, une
       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, mais consultez NOTES.

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 blocs de pile les plus anciens 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  depuis   la
       glibc 2.1.

ATTRIBUTS

       Pour une explication des termes utilisés dans cette section, consulter attributes(7).

       ┌────────────────────────────────────────────────────────┬──────────────────────┬─────────┐
       │InterfaceAttributValeur  │
       ├────────────────────────────────────────────────────────┼──────────────────────┼─────────┤
       │backtrace(), backtrace_symbols(),                       │ Sécurité des threads │ MT-Safe │
       │backtrace_symbols_fd()                                  │                      │         │
       └────────────────────────────────────────────────────────┴──────────────────────┴─────────┘

STANDARDS

       Ces fonctions sont des extensions GNU.

NOTES

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

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

       •  Les fonctions incorporées (« inline ») n’ont pas de blocs de pile.

       •  Avec les optimisations de type sous-routine finale (tail-call) font qu’un bloc de  pile
          en remplace un autre.

       •  backtrace()  et  backtrace_symbols_fd()  n'appellent  pas  malloc() explicitement, mais
          elles font partie de la libgcc qui est chargée dynamiquement à sa première utilisation.
          Le  chargement  dynamique  déclenche  habituellement un appel à malloc(3). Si vous avez
          besoin que certains appels à ces deux fonctions n'allouent pas  de  mémoire  (dans  les
          gestionnaires de signal, par exemple) vous devez vous assurer que la libgcc est chargée
          au préalable.

       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.

EXEMPLES

       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>

       #define BT_BUF_SIZE 100

       void
       myfunc3(void)
       {
           int nptrs;
           void *buffer[BT_BUF_SIZE];
           char **strings;

           nptrs = backtrace(buffer, BT_BUF_SIZE);
           printf("backtrace() returned %d addresses\n", nptrs);

           /* L’appel backtrace_symbols_fd(buffer, nptrs, STDOUT_FILENO)
              produirait une sortie semblable à ce qui suit : */

           strings = backtrace_symbols(buffer, nptrs);
           if (strings == NULL) {
               perror("backtrace_symbols");
               exit(EXIT_FAILURE);
           }

           for (size_t j = 0; j < nptrs; j++)
               printf("%s\n", strings[j]);

           free(strings);
       }

       static void   /* « static » signifie ne pas exporter le symbole... */
       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

       addr2line(1), gcc(1), gdb(1), ld(1), dlopen(3), malloc(3)

TRADUCTION

       La traduction française de cette  page  de  manuel  a  été  créée  par  Christophe  Blaess
       <https://www.blaess.fr/christophe/>,  Stéphan  Rafin  <stephan.rafin@laposte.net>, Thierry
       Vignaud <tvignaud@mandriva.com>, François Micaux, Alain  Portal  <aportal@univ-montp2.fr>,
       Jean-Philippe    Guérard   <fevrier@tigreraye.org>,   Jean-Luc   Coulon   (f5ibh)   <jean-
       luc.coulon@wanadoo.fr>,   Julien    Cristau    <jcristau@debian.org>,    Thomas    Huriaux
       <thomas.huriaux@gmail.com>, Nicolas François <nicolas.francois@centraliens.net>, Florentin
       Duneau <fduneau@gmail.com>, Simon Paillard <simon.paillard@resel.enst-bretagne.fr>,  Denis
       Barbier  <barbier@debian.org>,  David  Prévot  <david@tilapin.org>  et  Jean-Pierre Giraud
       <jean-pierregiraud@neuf.fr>

       Cette traduction est une documentation libre ; veuillez vous reporter  à  la  GNU  General
       Public   License   version 3  ⟨https://www.gnu.org/licenses/gpl-3.0.html⟩  concernant  les
       conditions de copie et de distribution. Il n'y a aucune RESPONSABILITÉ LÉGALE.

       Si vous découvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un
       message à ⟨debian-l10n-french@lists.debian.org⟩.