addrtosymstr man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

WALKCONTEXT(3C)						       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  pro‐
       gram  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 buf‐
       fer  argument,  and converts, where possible, each PC to a string indi‐
       cating 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 mal‐
       loc(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 buf‐
       fer argument, and converts, where possible, each PC to a	 string	 indi‐
       cating  the  module,  function,	and  offset  of	 each call site. These
       strings are written to the file descriptor specified in	the  fd	 argu‐
       ment. 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  cor‐
       rupted, 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 contain‐
       ing 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 par‐
       ticular, stdio(3C) and malloc(3C) cannot be used.

       The  walkstack(),  addrtosymstr(), printstack(), backtrace(), and back‐
       trace_symbols_fd() functions are Async-Signal-Safe and  can  be	called
       from  a	signal	handler.  The string representation generated by addr‐
       tosymstr() and displayed by printstack(), backtrace_symbols() and back‐
       trace_symbols_fd()  is unstable and will change depending on the infor‐
       mation available in the modules that comprise the stack trace.

       Tail-call optimizations on SPARC eliminate stack frames that would oth‐
       erwise 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.

				 Apr 10, 2007		       WALKCONTEXT(3C)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net