Manpage Monday: backtrace(3)

2008-10-27 14:43:48 UTC

New series: Manpage FridayMonday. Every Fridayother Monday, I will post a link to one manpage that comes with Mac OS X. [See update below.]

Today, it’s backtrace(3), which tells you about three functions:

SYNOPSIS

#include <execinfo.h>

int
backtrace(void** array, int size);

char**
backtrace_symbols(void* const* array, int size);

void
backtrace_symbols_fd(void* const* array, int size, int fd);

DESCRIPTION

These routines provide a mechanism to examine the current thread’s call stack.

backtrace() writes the function return addresses of the current call stack to the array of pointers referenced by array. At most, size pointers are written. The number of pointers actually written to array is returned.

backtrace_symbols() attempts to transform a call stack obtained by backtrace() into an array of human-readable strings using dladdr(). The array of strings returned has size elements. It is allocated using malloc() and should be released using free(). There is no need to free the individual strings in the array.

backtrace_symbols_fd() performs the same operation as backtrace_symbols(), but the resulting strings are immediately written to the file descriptor fd, and are not returned.

Added 2008-10-25: Here’s a test app to show the output.

File: print_backtrace.tbz

Output:

0   print_backtrace                     0x00001fc9 print_backtrace + 31
1   print_backtrace                     0x00001ff6 main + 11
2   print_backtrace                     0x00001f7e start + 54

In order:

  1. Index in the array of addresses
  2. Executable name
  3. Address
  4. Name + offset

UPDATE 2008-10-24 21:19 PDT: I’ve decided to change the schedule on this. Instead of Manpage Friday, I’ll do Manpage Monday, and it will be every two weeks. In between will be Framework Friday.

So this is now the first Manpage Monday post, and I will update its post date on Monday, the 27th. (I can’t update it now because WordPress won’t let me publish a post from the future—only schedule it. Grrr.) The week after that, November 7th will be the first Framework Friday. And in the week after that, November 10th will be the second Manpage Monday.

3 Responses to “Manpage Monday: backtrace(3)”

  1. Blake C. Says:

    Great idea! Hope this helps:

    http://www.macosxhints.com/article.php?story=20060204054031667

  2. Peter Hosey Says:

    It does. I’ve been using fully-qualified manpage URLs for some time, including here on the blog. ☺

  3. Peter Hosey Says:

    Oh, now I get why you mentioned it—I forgot to link to the manpage. Sorry about that. Fixed now.

Leave a Reply

Do not delete the second sentence.