Linux程序员手册 第3部分
更新日期： 2020-06-09

名称

backtrace，backtrace_symbols，backtrace_symbols_fd-支持应用程序自调试

语法

＃包括

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()在缓冲区指向的数组中返回调用程序的回溯。回溯是该程序当前活动的一系列函数调用。缓冲区所指向的数组中的每个项目的类型均为void *，并且是来自相应堆栈帧的返回地址。 size参数指定可以在缓冲区中存储的最大地址数。如果backtrace大于size，则返回对应于最近函数调用大小的地址；否则，返回0。要获取完整的回溯，请确保缓冲区和大小足够大。

给定缓冲区中backtrace()返回的地址集，backtrace_symbols()会将地址转换为以符号形式描述地址的字符串数组。 size参数指定缓冲区中的地址数。每个地址的符号表示形式由函数名称(如果可以确定)，函数的十六进制偏移量和实际返回地址(十六进制)组成。字符串指针数组的地址作为backtrace_symbols()的函数结果返回。该数组由backtrace_symbols()分配malloc(3)，并且必须由调用方释放。 (由指针数组指向的字符串不需要，也不应释放。)

backtrace_symbols_fd()的缓冲区和大小参数与backtrace_symbols()相同，但不是将字符串数组返回给调用方，而是将字符串(每行一个)写入文件描述符fd。 backtrace_symbols_fd()不会调用malloc(3)，因此可以在后一个函数可能失败的情况下使用，但请参见"注意"。

返回值

backtrace()返回缓冲区中返回的地址数量，该数量不大于size。如果返回值小于大小，则存储完整的回溯。如果它等于size，则可能已被截断，在这种情况下，不会返回最旧堆栈帧的地址。

成功后，backtrace_symbols()返回一个指向由调用调用的数组malloc(3)的指针；如果出错，则返回NULL。

版本

从2.1版开始，glibc中提供了backtrace()，backtrace_symbols()和backtrace_symbols_fd()。

属性

有关本节中使用的术语的说明，请参见attribute(7)。

遵循规范

这些功能是GNU扩展。

备注

这些函数对函数的返回地址如何存储在堆栈中进行了一些假设。请注意以下几点：

*

忽略帧指针(如gcc(1)的非零优化级别所暗示)可能会违反这些假设。

*

内联函数没有堆栈框架。

*

尾调用优化会导致一个堆栈框架替换另一个堆栈框架。

*

backtrace()和backtrace_symbols_fd()不会显式调用malloc()，但是它们是libgcc的一部分，它们在首次使用时会动态加载。动态加载通常会触发对malloc(3)的调用。如果需要对这两个函数的某些调用而不分配内存(例如，在信号处理程序中)，则需要确保预先加载了libgcc。

如果不使用特殊的链接器选项，则符号名称可能不可用。对于使用GNU链接器的系统，必须使用-rdynamic链接器选项。请注意，"静态"函数的名称未公开，并且在回溯中将不可用。

示例

下面的程序演示了backtrace()和backtrace_symbols()的用法。以下shell会话显示了我们在运行程序时可能看到的内容：

$ 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]

Program source

#include <execinfo.h>
#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>

#define BT_BUF_SIZE 100

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

    nptrs = backtrace(buffer, BT_BUF_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 donaqt 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);
}

另外参见

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

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。