1LIBUNWIND(3) Programming Library LIBUNWIND(3)
2
6 libunwind -- a (mostly) platform-independent unwind API
7
9 #include <libunwind.h>
10 int unw_getcontext(unw_context_t *);
12 int unw_init_local(unw_cursor_t *, unw_context_t *);
13 int unw_init_remote(unw_cursor_t *, unw_addr_space_t, void *);
14 int unw_step(unw_cursor_t *);
15 int unw_get_reg(unw_cursor_t *, unw_regnum_t, unw_word_t *);
16 int unw_get_fpreg(unw_cursor_t *, unw_regnum_t, unw_fpreg_t *);
17 int unw_set_reg(unw_cursor_t *, unw_regnum_t, unw_word_t);
18 int unw_set_fpreg(unw_cursor_t *, unw_regnum_t, unw_fpreg_t);
19 int unw_resume(unw_cursor_t *);
20 unw_addr_space_t unw_local_addr_space;
22 unw_addr_space_t unw_create_addr_space(unw_accessors_t, int);
23 void unw_destroy_addr_space(unw_addr_space_t);
24 unw_accessors_t unw_get_accessors(unw_addr_space_t);
25 void unw_flush_cache(unw_addr_space_t, unw_word_t, unw_word_t);
26 int unw_set_caching_policy(unw_addr_space_t, unw_caching_policy_t);
27 int unw_set_cache_size(unw_addr_space_t, size_t, int);
28 const char *unw_regname(unw_regnum_t);
30 int unw_get_proc_info(unw_cursor_t *, unw_proc_info_t *);
31 int unw_get_save_loc(unw_cursor_t *, int, unw_save_loc_t *);
32 int unw_is_fpreg(unw_regnum_t);
33 int unw_is_signal_frame(unw_cursor_t *);
34 int unw_get_proc_name(unw_cursor_t *, char *, size_t, unw_word_t *);
35 void _U_dyn_register(unw_dyn_info_t *);
37 void _U_dyn_cancel(unw_dyn_info_t *);
38
40 Libunwind is very easy to use when unwinding a stack from within a run‐
41 ning program. This is called local unwinding. Say you want to unwind
42 the stack while executing in some function F(). In this function, you
43 would call unw_getcontext() to get a snapshot of the CPU registers
44 (machine-state). Then you initialize an unwind cursor based on this
45 snapshot. This is done with a call to unw_init_local(). The cursor now
46 points to the current frame, that is, the stack frame that corresponds
47 to the current activation of function F(). The unwind cursor can then
48 be moved ``up'' (towards earlier stack frames) by calling unw_step().
49 By repeatedly calling this routine, you can uncover the entire
50 call-chain that led to the activation of function F(). A positive
51 return value from unw_step() indicates that there are more frames in
52 the chain, zero indicates that the end of the chain has been reached,
53 and any negative value indicates that some sort of error has occurred.
54 While it is not possible to directly move the unwind cursor in the
56 ``down'' direction (towards newer stack frames), this effect can be
57 achieved by making copies of an unwind cursor. For example, a program
58 that sometimes has to move ``down'' by one stack frame could maintain
59 two cursor variables: ``curr'' and ``prev''. The former would be used
60 as the current cursor and prev would be maintained as the ``previous
61 frame'' cursor by copying the contents of curr to prev right before
62 calling unw_step(). With this approach, the program could move one
63 step ``down'' simply by copying back prev to curr whenever that is nec‐
64 essary. In the most extreme case, a program could maintain a separate
65 cursor for each call frame and that way it could move up and down the
66 callframe-chain at will.
67 Given an unwind cursor, it is possible to read and write the CPU regis‐
69 ters that were preserved for the current stack frame (as identified by
70 the cursor). Libunwind provides several routines for this purpose:
71 unw_get_reg() reads an integer (general) register, unw_get_fpreg()
72 reads a floating-point register, unw_set_reg() writes an integer regis‐
73 ter, and unw_set_fpreg() writes a floating-point register. Note that,
74 by definition, only the preserved machine state can be accessed during
75 an unwind operation. Normally, this state consists of the callee-saved
76 (``preserved'') registers. However, in some special circumstances
77 (e.g., in a signal handler trampoline), even the caller-saved
78 (``scratch'') registers are preserved in the stack frame and, in those
79 cases, libunwind will grant access to them as well. The exact set of
80 registers that can be accessed via the cursor depends, of course, on
81 the platform. However, there are two registers that can be read on all
82 platforms: the instruction pointer (IP), sometimes also known as the
83 ``program counter'', and the stack pointer (SP). In libunwind, these
84 registers are identified by the macros UNW_REG_IP and UNW_REG_SP,
85 respectively.
86 Besides just moving the unwind cursor and reading/writing saved regis‐
88 ters, libunwind also provides the ability to resume execution at an
89 arbitrary stack frame. As you might guess, this is useful for imple‐
90 menting non-local gotos and the exception handling needed by some
91 high-level languages such as Java. Resuming execution with a particular
92 stack frame simply requires calling unw_resume() and passing the cursor
93 identifying the target frame as the only argument.
94 Normally, libunwind supports both local and remote unwinding (the lat‐
96 ter will be explained in the next section). However, if you tell libun‐
97 wind that your program only needs local unwinding, then a special
98 implementation can be selected which may run much faster than the
99 generic implementation which supports both kinds of unwinding. To
100 select this optimized version, simply define the macro UNW_LOCAL_ONLY
101 before including the headerfile <libunwind.h>. It is perfectly OK for
102 a single program to employ both local-only and generic unwinding. That
103 is, whether or not UNW_LOCAL_ONLY is defined is a choice that each
104 source-file (compilation-unit) can make on its own. Independent of the
105 setting(s) of UNW_LOCAL_ONLY, you'll always link the same library into
106 the program (normally -lunwind). Furthermore, the portion of libunwind
107 that manages unwind-info for dynamically generated code is not affected
108 by the setting of UNW_LOCAL_ONLY.
109 If we put all of the above together, here is how we could use libunwind
111 to write a function ``show_backtrace()'' which prints a classic stack
112 trace:
113 #define UNW_LOCAL_ONLY
115 #include <libunwind.h>
116 void show_backtrace (void) {
118 unw_cursor_t cursor; unw_context_t uc;
119 unw_word_t ip, sp;
120 unw_getcontext(&uc);
122 unw_init_local(&cursor, &uc);
123 while (unw_step(&cursor) > 0) {
124 unw_get_reg(&cursor, UNW_REG_IP, &ip);
125 unw_get_reg(&cursor, UNW_REG_SP, &sp);
126 printf ("ip = %lx, sp = %lx\n", (long) ip, (long) sp);
127 }
128 }
129
132 Libunwind can also be used to unwind a stack in a ``remote'' process.
133 Here, ``remote'' may mean another process on the same machine or even a
134 process on a completely different machine from the one that is running
135 libunwind. Remote unwinding is typically used by debuggers and
136 instruction-set simulators, for example.
137 Before you can unwind a remote process, you need to create a new
139 address-space object for that process. This is achieved with the
140 unw_create_addr_space() routine. The routine takes two arguments: a
141 pointer to a set of accessor routines and an integer that specifies the
142 byte-order of the target process. The accessor routines provide libun‐
143 wind with the means to communicate with the remote process. In particu‐
144 lar, there are callbacks to read and write the process's memory, its
145 registers, and to access unwind information which may be needed by
146 libunwind.
147 With the address space created, unwinding can be initiated by a call to
149 unw_init_remote(). This routine is very similar to unw_init_local(),
150 except that it takes an address-space object and an opaque pointer as
151 arguments. The routine uses these arguments to fetch the initial
152 machine state. Libunwind never uses the opaque pointer on its own, but
153 instead just passes it on to the accessor (callback) routines. Typi‐
154 cally, this pointer is used to select, e.g., the thread within a
155 process that is to be unwound.
156 Once a cursor has been initialized with unw_init_remote(), unwinding
158 works exactly like in the local case. That is, you can use unw_step()
159 to move ``up'' in the call-chain, read and write registers, or resume
160 execution at a particular stack frame by calling unw_resume.
161
163 Libunwind has been designed to enable unwinding across platforms
164 (architectures). Indeed, a single program can use libunwind to unwind
165 an arbitrary number of target platforms, all at the same time!
166 We call the machine that is running libunwind the host and the machine
168 that is running the process being unwound the target. If the host and
169 the target platform are the same, we call it native unwinding. If they
170 differ, we call it cross-platform unwinding.
171 The principle behind supporting native, cross-platform, and multi-plat‐
173 form unwinding is very simple: for native unwinding, a program includes
174 <libunwind.h> and uses the linker switch -lunwind. For cross-platform
175 unwinding, a program includes <libunwind-PLAT.h> and uses the linker
176 switch -lunwind-PLAT, where PLAT is the name of the target platform
177 (e.g., ia64 for IA-64, hppa-elf for ELF-based HP PA-RISC, or x86 for
178 80386). Multi-platform unwinding works exactly like cross-platform
179 unwinding, the only limitation is that a single source file (compila‐
180 tion unit) can include at most one libunwind header file. In other
181 words, the platform-specific support for each supported target needs to
182 be isolated in separate source files---a limitation that shouldn't be
183 an issue in practice.
184 Note that, by definition, local unwinding is possible only for the
186 native case. Attempting to call, e.g., unw_local_init() when targeting
187 a cross-platform will result in a link-time error (unresolved refer‐
188 ences).
189
191 All libunwind routines are thread-safe. What this means is that multi‐
192 ple threads may use libunwind simulatenously. However, any given cur‐
193 sor may be accessed by only one thread at any given time.
194 To ensure thread-safety, some libunwind routines may have to use lock‐
196 ing. Such routines must not be called from signal handlers (directly or
197 indirectly) and are therefore not signal-safe. The manual page for each
198 libunwind routine identifies whether or not it is signal-safe, but as a
199 general rule, any routine that may be needed for local unwinding is
200 signal-safe (e.g., unw_step() for local unwinding is signal-safe). For
201 remote-unwinding, none of the libunwind routines are guaranteed to be
202 signal-safe.
203
205 Libunwind provides the routines _U_dyn_register() and _U_dyn_cancel()
206 to register/cancel the information required to unwind through code that
207 has been generated at runtime (e.g., by a just-in-time (JIT) compiler).
208 It is important to register the information for all dynamically gener‐
209 ated code because otherwise, a debugger may not be able to function
210 properly or high-level language exception handling may not work as
211 expected.
212 The interface for registering and canceling dynamic unwind info has
214 been designed for maximum efficiency, so as to minimize the performance
215 impact on JIT-compilers. In particular, both routines are guaranteed to
216 execute in ``constant time'' (O(1)) and the data-structure encapsulat‐
217 ing the dynamic unwind info has been designed to facilitate sharing,
218 such that similar procedures can share much of the underlying informa‐
219 tion.
220 For more information on the libunwind support for dynamically generated
222 code, see libunwind-dynamic(3).
223
225 To speed up execution, libunwind may aggressively cache the information
226 it needs to perform unwinding. If a process changes during its life‐
227 time, this creates a risk of libunwind using stale data. For example,
228 this would happen if libunwind were to cache information about a shared
229 library which later on gets unloaded (e.g., via dlclose(3)).
230 To prevent the risk of using stale data, libunwind provides two facili‐
232 ties: first, it is possible to flush the cached information associated
233 with a specific address range in the target process (or the entire
234 address space, if desired). This functionality is provided by
235 unw_flush_cache(). The second facility is provided by
236 unw_set_caching_policy(), which lets a program select the exact caching
237 policy in use for a given address-space object. In particular, by
238 selecting the policy UNW_CACHE_NONE, it is possible to turn off caching
239 completely, therefore eliminating the risk of stale data alltogether
240 (at the cost of slower execution). By default, caching is enabled for
241 local unwinding only. The cache size can be dynamically changed with
242 unw_set_cache_size(), which also fluches the current cache.
243
245 libunwind.h
246 Headerfile to include for native (same platform) unwinding.
247 libunwind-PLAT.h
249 Headerfile to include when the unwind target runs on platform
250 PLAT. For example, to unwind an IA-64 program, the header file
251 libunwind-ia64.h should be included.
252 -lunwind
254 Linker-switch to add when building a program that does native
255 (same platform) unwinding.
256 -lunwind-PLAT
258 Linker-switch to add when building a program that unwinds a
259 program on platform PLAT. For example, to (cross-)unwind an
260 IA-64 program, the linker switch -lunwind-ia64 should be added.
261 Note: multiple such switches may need to be specified for pro‐
262 grams that can unwind programs on multiple platforms.
263
265 libunwind-dynamic(3), libunwind-ia64(3), libunwind-ptrace(3), libun‐
266 wind-setjmp(3), unw_create_addr_space(3), unw_destroy_addr_space(3),
267 unw_flush_cache(3), unw_get_accessors(3), unw_get_fpreg(3),
268 unw_get_proc_info(3), unw_get_proc_name(3), unw_get_reg(3), unw_getcon‐
269 text(3), unw_init_local(3), unw_init_remote(3), unw_is_fpreg(3),
270 unw_is_signal_frame(3), unw_regname(3), unw_resume(3),
271 unw_set_caching_policy(3), unw_set_cache_size(3), unw_set_fpreg(3),
272 unw_set_reg(3), unw_step(3), unw_strerror(3), _U_dyn_register(3),
273 _U_dyn_cancel(3)
274
276 David Mosberger-Tang
277 Email: dmosberger@gmail.com
278 WWW: http://www.nongnu.org/libunwind/.
279Programming Library 12 January 2017 LIBUNWIND(3)