Justin, > .TH BACKTRACE 3 "2006-05-26" GNU > . > .SH NAME > backtrace, backtrace_symbols, backtrace_symbols_fd \- support for application > self-debugging > .
These dots again... Please fix. > .SH SYNOPSIS Please change to use a .nf .fi block around the synopsis. Then you don't need the ".br" tags. > \fB#include <execinfo.h> Please change the synopsis formatting to the .BI style like fcntl.2. > \fBint backtrace(void **\fIbuffer\fP, int \fPsize\fP); > .br > \fBchar **backtrace_symbols(void *const *\fIbuffer\fP, int \fPsize\fP); > .br > \fBvoid backtrace_symbols_fd(void *const *\fIbuffer\fP, int \fPsize\fP, int > \fPfd\fP); > . > .SH DESCRIPTION > \fBbacktrace\fP() stores up to \fIsize\fP return addresses of the > most-recently called functions to the \fIbuffer\fP array. ^most-recently^most recently As noted, I prefer .B func () and .I arg I'd be happy if you would change this throughout. > \fBbacktrace_symbols\fP() accepts in \fIbuffer\fP an array of > \fIsize\fP return addresses, as generated by \fBbacktrace\fP(), and > returns an array of strings describing the functions containing those > addresses. This isn't strictly correct. It is something more like "strings describing those addresses. Backtrace() tries to work out which function contains each address. Please read the info pages for these functions, and page 48 of http://people.redhat.com/~drepper/tut1.ps. Have you covered all the relevant material that those sources cover. > \fBbacktrace_symbols_fd\fP() accepts the same \fIbuffer\fP and > \fPsize\fP parameters as \fBbacktrace_symbols\fP(), and writes to the > file descriptor \fIfd\fP the same descriptive strings, separated by > newlines. > . > .SH "RETURN VALUE" > \fBbacktrace\fP() returns the number of addresses stored, which is not > greater than \fIsize\fP. If it is less than \fIsize\fP, then the full > stacktrace was stored; if it is equal to \fIsize\fP, then the "stacktrace" is not English. Better to write sth like "then there was sufficient space to store all addresses"... > stacktrace may have been truncated, in which case, the addresses of > the least-recently called functions are not stored. Have you verified that last line? And "least-recently called" is not good wording; how about "the addresses corresponding to the oldest stack frames" > \fBbacktrace_symbols\fP() returns an array of \fIsize\fP strings, each > of which contains the function name, offset in bytes from the > beginning of that function, and the return address. The array (but > not the string elements) is allocated with \fBmalloc\fP(), and should > be freed when it is unused. \fBNULL\fP is returned on error. Don't format "NULL". > .SH EXAMPLE > .nf > /* make CFLAGS='-W -Wall -O0 -g' LDFLAGS='-rdynamic' gnubt */ > #include <execinfo.h> > #include <stdio.h> > #include <stdlib.h> > #include <unistd.h> > > int h(void) > { > void **vec=NULL; > size_t sz; > > for (sz=1; 1; sz<<=1) { > size_t ret; > if (NULL==(vec=realloc(vec, sz*sizeof(*vec)))) { > perror("realloc"); > exit(EXIT_FAILURE); > } > > ret=backtrace(vec, sz); > if (ret<sz) { > sz=ret; > break; > } > } > > backtrace_symbols_fd(vec, sz, STDOUT_FILENO); > free(vec); > return 0; > } > > int g(int n) > { > if (n!=0) return g(n-1); > return h(); > } > > /* Note the effect of marking a function "static" */ > static int f(int n) > { > return g(n); > } > > int main(int argc, char **argv) > { > if (argc!=2) { > fprintf(stderr, "Usage: %s <iterations>\n", *argv); > exit(EXIT_FAILURE); > } > > return f(atoi(argv[1])); > } > .fi > . > .SH "CONFORMING TO" > These functions are GNU extensions, and should not be used in programs > intended to be portable. > . > .SH NOTES > These functions make some assumptions about how a function's return > address is stored on the stack. Omission of the frame pointers (as > implied by any of \fBgcc\fP's non-zero optimization levels) may > violate those assumptions. But the above paragraph is less informative than the "info" page. > > Use of a special linker option may be necessary for > \fBbacktrace_symbols\fP() and \fPbacktrace_symbols_fd\fP() to resolve > the names of the symbols. For the GNU linker \fBld\fP, it is > necessary to pass \fB\-rdynamic\fP. Note that "static" function names > are never exposed, and won't be available in the backtrace. It is not just static -- it is anything that prevents symbol names being exported. E.g., linker maps can do this. Better to write sth like "If a function name is not exported (e.g., it is marked \fIstatic\fP), then that name will not be visible in the traceback." > \fBbacktrace_symbols\fP() requires that \fBmalloc\fP() function > correctly, whereas \fBbacktrace\fP() and \fBbacktrace_symbols_fd\fP() > do not (assuming that their arguments are allocated on the stack). > This is not insignificant in the situations where a backtrace is > useful. Avoid double negatives. "This is sometimes significant..." > . > .SH SEE ALSO > .BR malloc (3), not needed > .BR dladdr (3), Maybe better: dlopen(3) > .BR ld (1), > .BR gcc (1) Cheers, Michael -- Michael Kerrisk maintainer of Linux man pages Sections 2, 3, 4, 5, and 7 Want to help with man page maintenance? Grab the latest tarball at ftp://ftp.win.tue.nl/pub/linux-local/manpages/, read the HOWTOHELP file and grep the source files for 'FIXME'. -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
