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 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
       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 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 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

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Stable			   |
       +-----------------------------+-----------------------------+
       |MT-Level		     |See below.		   |
       +-----------------------------+-----------------------------+

       The backtrace_symbols() 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 Architecture Manual, Version 9. Santa Clara: Prentice Hall, 2000.

SunOS 5.11							    10 Apr 2007 						   walkcontext(3C)