Manual Pages for UNIX Operating System command usage for man backtrace

Standard C Library Functions                      walkcontext(3C)



NAME
     walkcontext,    addrtosymstr,     printstack,     backtrace,
     backtrace_symbols, backtrace_symbols_fd - walk stack pointed
     to by ucontext

SYNOPSIS
     #include 

     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 

     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]







SunOS 5.11          Last change: 10 Apr 2007                    1






Standard C Library Functions                      walkcontext(3C)



     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 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(3C)) to
     obtain symbolic symbol names. As a result, only global  sym-
     bols 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 pos-
     sible,  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 pos-
     sible,  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 func-
     tion is provided for glibc compatibility.




SunOS 5.11          Last change: 10 Apr 2007                    2






Standard C Library Functions                      walkcontext(3C)



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

       main()
       {
               bar();
               exit(0);



SunOS 5.11          Last change: 10 Apr 2007                    3






Standard C Library Functions                      walkcontext(3C)



       }

       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:














SunOS 5.11          Last change: 10 Apr 2007                    4






Standard C Library Functions                      walkcontext(3C)



     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Interface Stability         | Committed                   |
    |_____________________________|_____________________________|
    | 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  Architec-
     ture Manual, Version 9. Santa Clara: Prentice Hall, 2000.



































SunOS 5.11          Last change: 10 Apr 2007                    5