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.