BACKTRACE - Linux手册页

时间:2019-08-20 17:59:55  来源:igfitidea点击:

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)。

InterfaceAttributeValue
backtrace(),
backtrace_symbols(),
backtrace_symbols_fd()
Thread safetyMT-Safe

遵循规范

这些功能是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/