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);
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.23 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
Cette page de manuel a été traduite et est maintenue par Florentin
Duneau <fduneau AT gmail DOT com> et l’équipe francophone de traduction
de Debian.
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> ».