backtrace(3c)

1walkcontext(3C)          Standard C Library Functions          walkcontext(3C)
2
3
4

NAME

6       walkcontext,  addrtosymstr,  printstack,  backtrace, backtrace_symbols,
7       backtrace_symbols_fd - walk stack pointed to by ucontext
8

SYNOPSIS

10       #include <ucontext.h>
11
12       int walkcontext(const ucontext_t *uptr,
13            int (*operate_func)(uintptr_t, int, void *), void *usrarg);
14
15
16       int addrtosymstr(uintptr_t addr, char *buffer, int len);
17
18
19       int printstack(int fd);
20
21
22       #include <execinfo.h>
23
24       int backtrace(void **buffer, int size);
25
26
27       char **backtrace_symbols(void *const *buffer, int size);
28
29
30       void backtrace_symbols_fd(void *const *buffer, int size, int fd);
31
32

DESCRIPTION

34       The walkcontext() function walks the call stack  pointed  to  by  uptr,
35       which  can be obtained by a call to getcontext(2) or from a signal han‐
36       dler installed with the SA_SIGINFO flag.   The  walkcontext()  function
37       calls the user-supplied function operate_func for each routine found on
38       the call stack and each signal handler invoked. The  user  function  is
39       passed  three  arguments:  the PC at which the call or signal occurred,
40       the signal number that occurred at this PC (0 if no  signal  occurred),
41       and  the  third  argument passed to walkcontext(). If the user function
42       returns a non-zero value, walkcontext() returns without completing  the
43       callstack walk.
44
45
46       The  addrtosymstr()  function  attempts to convert a PC into a symbolic
47       representation of the form
48
49         objname'funcname+0xoffset[0xPC]
50
51
52
53       where objname is the module in which the PC is located, funcname is the
54       name  of  the  function, and offset is the offset from the beginning of
55       the function. The objname, funcname, and  offset  values  are  obtained
56       from  dladdr(3C)  and might not always be present. The resulting string
57       is written to the user-supplied buffer. Should the length of the string
58       be larger than the user-supplied buffer, only the portion of the string
59       that will fit is written and null-terminated.
60
61
62       The printstack() function uses walkcontext() to print a symbolic  stack
63       trace  to  the  specified file descriptor. This is useful for reporting
64       errors from signal handlers. The printstack() function  uses  dladdr1()
65       (see  dladdr(3C))  to  obtain  symbolic symbol names. As a result, only
66       global symbols are reported as symbol names by printstack().
67
68
69       The backtrace() function uses walkcontext() to generate a stack's  pro‐
70       gram  counter values for the calling thread and place these values into
71       the array specified by the buffer argument. The size argument specifies
72       the  maximum  number  of  program counters that will be recorded.  This
73       function is provided for compatibility with the GNU libc used on  Linux
74       systems, glibc.
75
76
77       The  backtrace_symbols()  function  translates  the  numerical  program
78       counter values previously recorded by a call to backtrace() in the buf‐
79       fer  argument,  and converts, where possible, each PC to a string indi‐
80       cating the module, function and offset of each call site. The number of
81       symbols present in the array must be passed in with the size argument.
82
83
84       The set of strings is returned in an array obtained from a call to mal‐
85       loc(3C). It is the responsibility of the caller to  pass  the  returned
86       pointer  to  free().   The individual strings must not be freed.  Since
87       malloc() is used to obtain the needed space, this function  is  MT-Safe
88       rather than Async-Signal-Safe and cannot be used reliably from a signal
89       handler.  This function is provided for glibc compatibility.
90
91
92       The backtrace_symbols_fd() function translates  the  numerical  program
93       counter values previously recorded by a call to backtrace() in the buf‐
94       fer argument, and converts, where possible, each PC to a  string  indi‐
95       cating  the  module,  function,  and  offset  of  each call site. These
96       strings are written to the file descriptor specified in  the  fd  argu‐
97       ment. This function is provided for glibc compatibility.
98

RETURN VALUES

100       Upon  successful  completion,  walkcontext() and printstack() return 0.
101       If walkcontext() cannot read the stack or the stack trace appears  cor‐
102       rupted, both functions return -1.
103
104
105       The  addrtosymstr() function returns the number of characters necessary
106       to hold the entire string representation  of  the  passed  in  address,
107       irrespective of the size of the user-supplied buffer.
108
109
110       The backtrace() function returns the number of stack frames captured.
111
112
113       The backtrace_symbols() function returns a pointer to an array contain‐
114       ing string representations of the calling sequence.
115

ERRORS

117       No error values are defined.
118

USAGE

120       The walkcontext() function is  typically  used  to  obtain  information
121       about  the  call  stack  for  error reporting, performance analysis, or
122       diagnostic purposes. Many library functions are  not  Async-Signal-Safe
123       and should not be used from a signal handler. If walkcontext() is to be
124       called from a signal handler, careful programming is required.  In par‐
125       ticular, stdio(3C) and malloc(3C) cannot be used.
126
127
128       The  walkstack(),  addrtosymstr(), printstack(), backtrace(), and back‐
129       trace_symbols_fd() functions are Async-Signal-Safe and  can  be  called
130       from  a  signal  handler.  The string representation generated by addr‐
131       tosymstr() and displayed by printstack(), backtrace_symbols() and back‐
132       trace_symbols_fd()  is unstable and will change depending on the infor‐
133       mation available in the modules that comprise the stack trace.
134
135
136       Tail-call optimizations on SPARC eliminate stack frames that would oth‐
137       erwise be present.  For example, if the code is of the form
138
139         #include <stdio.h>
140
141         main()
142         {
143                 bar();
144                 exit(0);
145         }
146
147         bar()
148         {
149                 int a;
150                 a = foo(fileno(stdout));
151                 return (a);
152         }
153
154         foo(int file)
155         {
156                 printstack(file);
157         }
158
159
160
161       compiling without optimization will yield a stack trace of the form
162
163         /tmp/q:foo+0x8
164         /tmp/q:bar+0x14
165         /tmp/q:main+0x4
166         /tmp/q:_start+0xb8
167
168
169
170       whereas with higher levels of optimization the output is
171
172         /tmp/q:main+0x10
173         /tmp/q:_start+0xb8
174
175
176
177       since both the call to foo() in main and the call to bar() in foo() are
178       handled as tail calls that perform a return or  restore  in  the  delay
179       slot. For further information, see The SPARC Architecture Manual.
180

ATTRIBUTES

182       See attributes(5) for descriptions of the following attributes:
183
184
185
186
187       ┌─────────────────────────────┬─────────────────────────────┐
188       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
189       ├─────────────────────────────┼─────────────────────────────┤
190       │Interface Stability          │Stable                       │
191       ├─────────────────────────────┼─────────────────────────────┤
192       │MT-Level                     │See below.                   │
193       └─────────────────────────────┴─────────────────────────────┘
194
195
196       The  backtrace_symbols()  function  is MT-Safe. The remaining functions
197       are Async-Signal-Safe.
198