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.
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.44 du projet
man-pages Linux.
Une description du projet et des instructions pour signaler des anomalies
peuvent être trouvées à l'adresse
<
http://www.kernel.org/doc/man-pages/>.
TRADUCTION¶
Depuis 2010, cette traduction est maintenue à l'aide de l'outil po4a
<
http://po4a.alioth.debian.org/> par l'équipe de traduction
francophone au sein du projet perkamon
<
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> ».