walkcontext(3C)
NAME
walkcontext, printstack - walk stack pointed to by ucontext
SYNOPSIS
#include <ucontext.h>
int walkcontext(const ucontext_t *uptr, int
(*operate_func)(uintptr_t, int, void *), void *usrarg);
int printstack(int fd);
DESCRIPTION
The walkcontext() function walks the call stack pointed to
by uptr, which can be obtained by a call to getcontext(2) or
from a signal handler installed with the SA_SIGINFO flag.
The walkcontext() function calls the user-supplied function
operate_func for each routine found on the call stack and
each signal handler invoked. The user function is passed
three arguments: the PC at which the call or signal occured,
the signal number that occured at this PC (0 if no signal
occured), and the third argument passed to walkcontext(). If
the user function returns a non-zero value, walkcontext()
returns without completing the callstack walk.
The printstack() function uses walkcontext() to print a sym-
bolic stack trace to the specified file descriptor. This is
useful for reporting errors from signal handlers. The
printstack() function uses dladdr1() (see dladdr(3DL)) to
obtain symbolic symbol names. As a result, only global sym-
bols are reported as symbol names by printstack().
RETURN VALUES
Upon successful completion, walkstack() and printstack()
return 0. If walkstack() cannot read the stack or the stack
trace appears corrupted, both functions return -1.
ERRORS
No error values are defined.
USAGE
The walkcontext() function is typically used to obtain
information about the call stack for error reporting, per-
formance analysis, or diagnostic purposes. Many library
functions are not Async-Signal-Safe and should not be used
from a signal handler. If walkcontext() is to be called from
a signal handler, careful programming is required. In par-
ticular, stdio(3C) and malloc(3C) cannot be used.
The printstack() function is Async-Signal-Safe and can be
called from a signal handler. The output format from
printstack() is unstable, as it varies with the scope of the
routines.
Tail-call optimizations on SPARC eliminate stack frames that
would otherwise be present. For example, if the code is of
the form
#include <stdio.h>
main()
{
bar();
exit(0);
}
bar()
{
int a;
a = foo(fileno(stdout));
return (a);
}
foo(int file)
{
printstack(file);
}
compiling without optimization will yield a stack trace of
the form
/tmp/q:foo+0x8
/tmp/q:bar+0x14
/tmp/q:main+0x4
/tmp/q:_start+0xb8
whereas with higher levels of optimization the output is
/tmp/q:main+0x10
/tmp/q:_start+0xb8
since both the call to foo() in main and the call to bar()
in foo() are handled as tail calls that perform a return or
restore in the delay slot. For further information, see The
SPARC Architecture Manual.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Interface Stability | Stable |
|_____________________________|_____________________________|
| MT-Level | Async-Signal-Safe |
|_____________________________|_____________________________|
SEE ALSO
intro(2), getcontext(2), sigaction(2), dladdr(3DL),
siginfo(3HEAD), attributes(5)
Weaver, David L. and Tom Germond, eds. The SPARC Architec-
ture Manual, Version 9. Santa Clara: Prentice Hall, 2000.
Man(1) output converted with
man2html