Hi Justin,
did you get my previous mail about this manual page?
Michael also replied to it, marking the comments he
agreed with.
One of the comments was about the "most recently
called functions" expression, I suggested replacing it
with either "the list of active function calls in the
current thread", or "the function call backtrace".
The second (and not addressed in the newer manpage)
concerns the cases when the backtrace might not be
what you expected - I mentioned inlined functions,
which won't show up in the backtrace; all the cases
where a backtrace might not be what you expect are
described in the libc manual, IIRC.
In the NOTES section, you say "backtrace_symbols
requires that malloc function properly" - I would
change that to "backtrace_symbols will fail if it
fails to allocate the string it returns with malloc",
because I guess malloc should always function
properly, and returning NULL when running out of
memory is part of that.
Also, I don't understand the purpose of the loop you
wanted to put in the example, it might be confusing
for some people and doesn't achieve anything special
(or useful), besides printing some truncated stack
traces when sz is too small.
I think example code should be as simple as possible,
because many people are going to just copy/paste it
and then maybe change it.
Sorry for the belated answer,
Stefan.
--- Justin Pryzby <[EMAIL PROTECTED]>
wrote:
> Included is a revised copy of backtrace.3.
>
> Michael:
>
> I was tempted to use an alternate loop condition in
> h():
>
> for (sz=1; (sz&(sz-1))==0 && (sz<<=1); ) {
> if (NULL==(vec=realloc(vec,
> sz*sizeof(*vec)))) {
> perror("realloc");
> exit(EXIT_FAILURE);
> }
>
> sz=backtrace(vec, sz);
> }
>
> but I anticipated that you feel this is not the
> place to teach people
> about the properties of powers of two. I mention it
> here in case I
> was wrong :)
>
> BTW, |expand -t4 should be useful in the future when
> I forget your tab
> preference.
>
>
> .\" Copyright (C) 2006 Justin Pryzby
> <[EMAIL PROTECTED]>
> .\"
> .\" Permission is hereby granted, free of charge, to
> any person obtaining
> .\" a copy of this software and associated
> documentation files (the
> .\" "Software"), to deal in the Software without
> restriction, including
> .\" without limitation the rights to use, copy,
> modify, merge, publish,
> .\" distribute, sublicense, and/or sell copies of
> the Software, and to
> .\" permit persons to whom the Software is furnished
> to do so, subject to
> .\" the following conditions:
> .\"
> .\" The above copyright notice and this permission
> notice shall be
> .\" included in all copies or substantial portions
> of the Software.
> .\"
> .\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT
> WARRANTY OF ANY KIND,
> .\" EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO
> THE WARRANTIES OF
> .\" MERCHANTABILITY, FITNESS FOR A PARTICULAR
> PURPOSE AND NONINFRINGEMENT.
> .\" IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
> HOLDERS BE LIABLE FOR ANY
> .\" CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
> ACTION OF CONTRACT,
> .\" TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
> CONNECTION WITH THE
> .\" SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
> SOFTWARE.
> .\"
> .\" References:
> .\" glibc manual and source
> .TH BACKTRACE 3 "2006-05-26" GNU
> .
> .SH NAME
> backtrace, backtrace_symbols, backtrace_symbols_fd
> \- support for application self-debugging
> .
> .SH SYNOPSIS
> \fB#include <execinfo.h>
>
> \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.
>
> \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.
>
> \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 may have been truncated, in which case,
> the addresses of
> the least-recently called functions are not stored.
>
> \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.
> .
> .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.
>
>
=== message truncated ===
__________________________________________________
Do You Yahoo!?
Tired of spam? Yahoo! Mail has the best spam protection around
http://mail.yahoo.com
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
