Standard C Library Functions walkcontext(3C)
NAME
walkcontext, addrtosymstr, printstack, backtrace,
backtracesymbols, backtracesymbolsfd - walk stack pointed
to by ucontext
SYNOPSIS
#include
int walkcontext(const ucontextt *uptr,
int (*operatefunc)(uintptrt, int, void *), void *usrarg);
int addrtosymstr(uintptrt addr, char *buffer, int len);
int printstack(int fd);
#include
int backtrace(void **buffer, int size);
char **backtracesymbols(void *const *buffer, int size);
void backtracesymbolsfd(void *const *buffer, int size, 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 SASIGINFO flag.
The walkcontext() function calls the user-supplied function
operatefunc 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
occurred, the signal number that occurred at this PC (0 if
no signal occurred), and the third argument passed to
walkcontext(). If the user function returns a non-zero
value, walkcontext() returns without completing the
callstack walk.
The addrtosymstr() function attempts to convert a PC into a
symbolic representation of the form
objname'funcname]0xoffset[0xPC]
SunOS 5.11 Last change: 10 Apr 2007 1
Standard C Library Functions walkcontext(3C)
where objname is the module in which the PC is located,
funcname is the name of the function, and offset is the
offset from the beginning of the function. The objname,
funcname, and offset values are obtained from dladdr(3C) and
might not always be present. The resulting string is written
to the user-supplied buffer. Should the length of the string
be larger than the user-supplied buffer, only the portion of
the string that will fit is written and null-terminated.
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(3C)) to
obtain symbolic symbol names. As a result, only global sym-
bols are reported as symbol names by printstack().
The backtrace() function uses walkcontext() to generate a
stack's program counter values for the calling thread and
place these values into the array specified by the buffer
argument. The size argument specifies the maximum number of
program counters that will be recorded. This function is
provided for compatibility with the GNU libc used on Linux
systems, glibc.
The backtracesymbols() function translates the numerical
program counter values previously recorded by a call to
backtrace() in the buffer argument, and converts, where pos-
sible, each PC to a string indicating the module, function
and offset of each call site. The number of symbols present
in the array must be passed in with the size argument.
The set of strings is returned in an array obtained from a
call to malloc(3C). It is the responsibility of the caller
to pass the returned pointer to free(). The individual
strings must not be freed. Since malloc() is used to obtain
the needed space, this function is MT-Safe rather than
Async-Signal-Safe and cannot be used reliably from a signal
handler. This function is provided for glibc compatibility.
The backtracesymbolsfd() function translates the numerical
program counter values previously recorded by a call to
backtrace() in the buffer argument, and converts, where pos-
sible, each PC to a string indicating the module, function,
and offset of each call site. These strings are written to
the file descriptor specified in the fd argument. This func-
tion is provided for glibc compatibility.
SunOS 5.11 Last change: 10 Apr 2007 2
Standard C Library Functions walkcontext(3C)
RETURN VALUES
Upon successful completion, walkcontext() and printstack()
return 0. If walkcontext() cannot read the stack or the
stack trace appears corrupted, both functions return -1.
The addrtosymstr() function returns the number of characters
necessary to hold the entire string representation of the
passed in address, irrespective of the size of the user-
supplied buffer.
The backtrace() function returns the number of stack frames
captured.
The backtracesymbols() function returns a pointer to an
array containing string representations of the calling
sequence.
ERORS
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 walkstack(), addrtosymstr(), printstack(), backtrace(),
and backtracesymbolsfd() functions are Async-Signal-Safe
and can be called from a signal handler. The string
representation generated by addrtosymstr() and displayed by
printstack(), backtracesymbols() and backtracesymbolsfd()
is unstable and will change depending on the information
available in the modules that comprise the stack trace.
Tail-call optimizations on SPARC eliminate stack frames that
would otherwise be present. For example, if the code is of
the form
#include
main()
{
bar();
exit(0);
SunOS 5.11 Last change: 10 Apr 2007 3
Standard C Library Functions walkcontext(3C)
}
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.
ATRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
SunOS 5.11 Last change: 10 Apr 2007 4
Standard C Library Functions walkcontext(3C)
ATRIBUTE TYPE ATRIBUTE VALUE
Interface Stability Stable
MT-Level See below.
The backtracesymbols() function is MT-Safe. The remaining
functions are Async-Signal-Safe.
SEE ALSO
Intro(2), getcontext(2), sigaction(2), dladdr(3C),
siginfo.h(3HEAD), attributes(5)
Weaver, David L. and Tom Germond, eds. The SPARC Architec-
ture Manual, Version 9. Santa Clara: Prentice Hall, 2000.
SunOS 5.11 Last change: 10 Apr 2007 5
|
