backtrace execinfo.h

原文链接： http://man7.org/linux/man-pages/man3/backtrace.3.html

http://man7.org/linux/man-pages/man3/backtrace.3.html

BACKTRACE(3)              linux编程者手册             BACKTRACE(3)

名称         top

       backtrace,  backtrace_symbols,  backtrace_symbols_fd  -  支持app自调试

声明         top

       #include 

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

描述         top

backtrace() 返回调用程序的一个backtrace到一个buffer指定的数组中。一个backtrace是该程序当前激活的函数序列。由buffer指针指向的数组中的每个条目是void*类型， 它是从相应的栈帧的返回地址。参数size指定了可存储在buffer内的最多地址个数。如果backtrace超过了size，只能保存最近调用的size个函数的地址;为了获取完整的backtrace，要确保buffer和size要足够的大。

考虑到由backtrace()返回的是地址的集合，不利于查看，backtrace_symbols()把地址集合转换成描述该地址符号标识的字符串数组。参数size指定buffer中地址的个数。每个地址的符号标识包含有函数名(如果可能确定的话)，该函数的十六进制偏移，实际的返回地址(以十六进制标识)。函数backtrace_symbols()返回的是字符串指针数组的地址。这个地址是由函数backtrace_symbols()使用malloc创建的，需要我们自己去释放。(该指针数组指向的字符串不需要，也不应该释放)。

backtrace_symbols_fd()跟backtrace_symbols()有相同的buffer和size参数，但是，不同的是，它不是返回字符串数组，而是写字符串(每个字符串一行)到文件描述符fd中。backtrace_symbols_fd()不调用malloc。

RETURN VALUE         top

       backtrace() returns the number of addresses returned in buffer, which
       is not greater than size.  If the return value is less than size,
       then the full backtrace was stored; if it is equal to size, then it
       may have been truncated, in which case the addresses of the oldest
       stack frames are not returned.

       On success, backtrace_symbols() returns a pointer to the array
       malloc(3)ed by the call; on error, NULL is returned.

VERSIONS         top

       backtrace(), backtrace_symbols(), and backtrace_symbols_fd() are
       provided in glibc since version 2.1.

ATTRIBUTES         top

       For an explanation of the terms used in this section, see
       attributes(7).

       ┌───────────────────────┬───────────────┬─────────┐
       │Interface              │ Attribute     │ Value   │
       ├───────────────────────┼───────────────┼─────────┤
       │backtrace(),           │ Thread safety │ MT-Safe │
       │backtrace_symbols(),   │               │         │
       │backtrace_symbols_fd() │               │         │
       └───────────────────────┴───────────────┴─────────┘

CONFORMING TO         top

       These functions are GNU extensions.

NOTES         top

       These functions make some assumptions about how a function's return
       address is stored on the stack.  Note the following:

       *  Omission of the frame pointers (as implied by any of gcc(1)'s
          nonzero optimization levels) may cause these assumptions to be
          violated.

       *  Inlined functions do not have stack frames.

       *  Tail-call optimization causes one stack frame to replace another.

       *  backtrace() and backtrace_symbols_fd() don't call malloc()
          explicitly, but they are part of libgcc, which gets loaded
          dynamically when first used.  Dynamic loading usually triggers a
          call to malloc(3).  If you need certain calls to these two
          functions to not allocate memory (in signal handlers, for
          example), you need to make sure libgcc is loaded beforehand.

       The symbol names may be unavailable without the use of special linker
       options.  For systems using the GNU linker, it is necessary to use
       the -rdynamic linker option.  Note that names of "static" functions
       are not exposed, and won't be available in the backtrace.

EXAMPLE         top

#include
#include
 

#include
#include
#include
#include

#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 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);
}
 

SEE ALSO         top

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

COLOPHON         top

       This page is part of release 5.02 of the Linux man-pages project.  A
       description of the project, information about reporting bugs, and the
       latest version of this page, can be found at
       https://www.kernel.org/doc/man-pages/.