backtrace(3) Library Functions Manual backtrace(3) NOM backtrace, backtrace_symbols, backtrace_symbols_fd - Outils d'auto-debogage d'applications BIBLIOTHEQUE Bibliotheque C standard (libc, -lc) SYNOPSIS #include 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 pointe par buffer. Une trace est une serie d'appels de fonction actuellement actifs d'un programme. Chaque element du tableau pointe par buffer est de type void *, et correspond a l'adresse de retour du bloc de pile (stack frame) correspondant. Le parametre size specifie le nombre maximal 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 renvoyees. Pour obtenir une trace complete, assurez-vous que buffer et size soient assez grands. A partir des adresses renvoyees par backtrace() dans le buffer, backtrace_symbols() traduit les adresses en un tableau de chaines qui associe des symboles 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 renvoi. L'adresse du tableau de pointeurs 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, une 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, mais consultez NOTES. VALEUR RENVOYEE 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 blocs de pile les plus anciens 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. ATTRIBUTS Pour une explication des termes utilises dans cette section, consulter attributes(7). +---------------------------------+--------------------------+---------+ |Interface | Attribut | Valeur | +---------------------------------+--------------------------+---------+ |backtrace(), | Securite des threads | MT-Safe | |backtrace_symbols(), | | | |backtrace_symbols_fd() | | | +---------------------------------+--------------------------+---------+ STANDARDS GNU. HISTORIQUE glibc 2.1. NOTES Ces fonctions font des suppositions sur la facon dont l'adresse renvoyee d'une fonction est sauvegardee dans la pile. Prenez note des points suivants : - L'omission du pointeur de bloc (comme le fait gcc(1) avec les niveaux d'optimisation differents de zero) peut etre incompatible avec ces suppositions. - Les fonctions incorporees (<< 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 chargee dynamiquement a sa premiere utilisation. Le chargement dynamique declenche habituellement un appel a malloc(3). Si vous avez besoin que certains appels a ces deux fonctions n'allouent pas de memoire (dans les gestionnaires de signal, par exemple) vous devez vous assurer que la libgcc est chargee au prealable. 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. EXEMPLES 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 #include #include #include #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 a 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 francaise de cette page de manuel a ete creee par Christophe Blaess , Stephan Rafin , Thierry Vignaud , Francois Micaux, Alain Portal , Jean-Philippe Guerard , Jean-Luc Coulon (f5ibh) , Julien Cristau , Thomas Huriaux , Nicolas Francois , Florentin Duneau , Simon Paillard , Denis Barbier , David Prevot et Jean-Pierre Giraud Cette traduction est une documentation libre ; veuillez vous reporter a la GNU General Public License version 3 concernant les conditions de copie et de distribution. Il n'y a aucune RESPONSABILITE LEGALE. Si vous decouvrez un bogue dans la traduction de cette page de manuel, veuillez envoyer un message a . Pages du manuel de Linux 6.8 2 mai 2024 backtrace(3)