Tribblix: manual page: walkcontext.3c

WALKCONTEXT(3C) Standard C Library Functions WALKCONTEXT(3C)

NAME

walkcontext, addrtosymstr, printstack, backtrace, backtrace_symbols,
backtrace_symbols_fd - 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 addrtosymstr(uintptr_t addr, char *buffer, int len);

int printstack(int fd);

#include <execinfo.h>

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

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

void backtrace_symbols_fd(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 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 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]

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 symbolic
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 symbols 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 backtrace_symbols() function translates the numerical program
counter values previously recorded by a call to backtrace() in the
buffer argument, and converts, where possible, 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 backtrace_symbols_fd() function translates the numerical program
counter values previously recorded by a call to backtrace() in the
buffer argument, and converts, where possible, 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 function is provided for glibc compatibility.

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 backtrace_symbols() function returns a pointer to an array
containing string representations of the calling sequence.

ERRORS

No error values are defined.

USAGE

The walkcontext() function is typically used to obtain information
about the call stack for error reporting, performance 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
particular, stdio(3C) and malloc(3C) cannot be used.

The walkstack(), addrtosymstr(), printstack(), backtrace(), and
backtrace_symbols_fd() functions are Async-Signal-Safe and can be
called from a signal handler. The string representation
generated by addrtosymstr() and displayed by printstack(),
backtrace_symbols() and backtrace_symbols_fd() 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 <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