Provided by:
manpages-fr-dev_3.27fr1.4-1_all 
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> >>.