Unix/Linux Go Back    


man page for backtrace_symbols_fd (all section 3c)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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 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 call-
       stack 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  func-
       tion,  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 speci-
       fied 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 argu-
       ment. 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  previ-
       ously recorded by a call to backtrace() in the buffer argument, and converts, where possi-
       ble, 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 func-
       tion 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 previ-
       ously recorded by a call to backtrace() in the buffer argument, and converts, where possi-
       ble,  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.

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-sup-
       plied buffer.

       The backtrace() function returns the number of stack frames captured.

       The backtrace_symbols() function returns a pointer to an array containing string represen-
       tations 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  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_sym-
       bols() 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)
Unix & Linux Commands & Man Pages : 2000 - 2016 Unix and Linux Forums


All times are GMT -4. The time now is 07:30 PM.