sunos man page for printstack

walkcontext(3C) 					   Standard C Library Functions 					   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 han-
       dler 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 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().

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.

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 diag-
       nostic  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 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 attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Stable			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |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 Architecture Manual, Version 9. Santa Clara: Prentice Hall, 2000.

SunOS 5.10							    1 Mar 2004							   walkcontext(3C)