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 (ma‐
44 chine-state). Then you initialize an unwind cursor based on this snap‐
45 shot. 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 re‐
51 turn value from unw_step() indicates that there are more frames in the
52 chain, zero indicates that the end of the chain has been reached, and
53 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, re‐
85 spectively.
86 Besides just moving the unwind cursor and reading/writing saved regis‐
88 ters, libunwind also provides the ability to resume execution at an ar‐
89 bitrary stack frame. As you might guess, this is useful for implement‐
90 ing 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 im‐
98 plementation can be selected which may run much faster than the generic
99 implementation which supports both kinds of unwinding. To select this
100 optimized version, simply define the macro UNW_LOCAL_ONLY before in‐
101 cluding the headerfile <libunwind.h>. It is perfectly OK for a single
102 program to employ both local-only and generic unwinding. That is,
103 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 in‐
136 struction-set simulators, for example.
137 Before you can unwind a remote process, you need to create a new ad‐
139 dress-space object for that process. This is achieved with the unw_cre‐
140 ate_addr_space() routine. The routine takes two arguments: a pointer to
141 a set of accessor routines and an integer that specifies the byte-order
142 of the target process. The accessor routines provide libunwind with the
143 means to communicate with the remote process. In particular, there are
144 callbacks to read and write the process's memory, its registers, and to
145 access unwind information which may be needed by libunwind.
146 With the address space created, unwinding can be initiated by a call to
148 unw_init_remote(). This routine is very similar to unw_init_local(),
149 except that it takes an address-space object and an opaque pointer as
150 arguments. The routine uses these arguments to fetch the initial ma‐
151 chine state. Libunwind never uses the opaque pointer on its own, but
152 instead just passes it on to the accessor (callback) routines. Typi‐
153 cally, this pointer is used to select, e.g., the thread within a
154 process that is to be unwound.
155 Once a cursor has been initialized with unw_init_remote(), unwinding
157 works exactly like in the local case. That is, you can use unw_step()
158 to move ``up'' in the call-chain, read and write registers, or resume
159 execution at a particular stack frame by calling unw_resume.
160
162 Libunwind has been designed to enable unwinding across platforms (ar‐
163 chitectures). Indeed, a single program can use libunwind to unwind an
164 arbitrary number of target platforms, all at the same time!
165 We call the machine that is running libunwind the host and the machine
167 that is running the process being unwound the target. If the host and
168 the target platform are the same, we call it native unwinding. If they
169 differ, we call it cross-platform unwinding.
170 The principle behind supporting native, cross-platform, and multi-plat‐
172 form unwinding is very simple: for native unwinding, a program includes
173 <libunwind.h> and uses the linker switch -lunwind. For cross-platform
174 unwinding, a program includes <libunwind-PLAT.h> and uses the linker
175 switch -lunwind-PLAT, where PLAT is the name of the target platform
176 (e.g., ia64 for IA-64, hppa-elf for ELF-based HP PA-RISC, or x86 for
177 80386). Multi-platform unwinding works exactly like cross-platform un‐
178 winding, the only limitation is that a single source file (compilation
179 unit) can include at most one libunwind header file. In other words,
180 the platform-specific support for each supported target needs to be
181 isolated in separate source files---a limitation that shouldn't be an
182 issue in practice.
183 Note that, by definition, local unwinding is possible only for the na‐
185 tive case. Attempting to call, e.g., unw_local_init() when targeting a
186 cross-platform will result in a link-time error (unresolved refer‐
187 ences).
188
190 All libunwind routines are thread-safe. What this means is that multi‐
191 ple threads may use libunwind simultaneously. However, any given cur‐
192 sor may be accessed by only one thread at any given time.
193 To ensure thread-safety, some libunwind routines may have to use lock‐
195 ing. Such routines must not be called from signal handlers (directly or
196 indirectly) and are therefore not signal-safe. The manual page for each
197 libunwind routine identifies whether or not it is signal-safe, but as a
198 general rule, any routine that may be needed for local unwinding is
199 signal-safe (e.g., unw_step() for local unwinding is signal-safe). For
200 remote-unwinding, none of the libunwind routines are guaranteed to be
201 signal-safe.
202
204 Libunwind provides the routines _U_dyn_register() and _U_dyn_cancel()
205 to register/cancel the information required to unwind through code that
206 has been generated at runtime (e.g., by a just-in-time (JIT) compiler).
207 It is important to register the information for all dynamically gener‐
208 ated code because otherwise, a debugger may not be able to function
209 properly or high-level language exception handling may not work as ex‐
210 pected.
211 The interface for registering and canceling dynamic unwind info has
213 been designed for maximum efficiency, so as to minimize the performance
214 impact on JIT-compilers. In particular, both routines are guaranteed to
215 execute in ``constant time'' (O(1)) and the data-structure encapsulat‐
216 ing the dynamic unwind info has been designed to facilitate sharing,
217 such that similar procedures can share much of the underlying informa‐
218 tion.
219 For more information on the libunwind support for dynamically generated
221 code, see libunwind-dynamic(3).
222
224 To speed up execution, libunwind may aggressively cache the information
225 it needs to perform unwinding. If a process changes during its life‐
226 time, this creates a risk of libunwind using stale data. For example,
227 this would happen if libunwind were to cache information about a shared
228 library which later on gets unloaded (e.g., via dlclose(3)).
229 To prevent the risk of using stale data, libunwind provides two facili‐
231 ties: first, it is possible to flush the cached information associated
232 with a specific address range in the target process (or the entire ad‐
233 dress space, if desired). This functionality is provided by
234 unw_flush_cache(). The second facility is provided by
235 unw_set_caching_policy(), which lets a program select the exact caching
236 policy in use for a given address-space object. In particular, by se‐
237 lecting the policy UNW_CACHE_NONE, it is possible to turn off caching
238 completely, therefore eliminating the risk of stale data altogether (at
239 the cost of slower execution). By default, caching is enabled for local
240 unwinding only. The cache size can be dynamically changed with
241 unw_set_cache_size(), which also flushes the current cache.
242
244 libunwind.h
245 Headerfile to include for native (same platform) unwinding.
246 libunwind-PLAT.h
248 Headerfile to include when the unwind target runs on platform
249 PLAT. For example, to unwind an IA-64 program, the header file
250 libunwind-ia64.h should be included.
251 -lunwind
253 Linker-switch to add when building a program that does native
254 (same platform) unwinding.
255 -lunwind-PLAT
257 Linker-switch to add when building a program that unwinds a
258 program on platform PLAT. For example, to (cross-)unwind an
259 IA-64 program, the linker switch -lunwind-ia64 should be added.
260 Note: multiple such switches may need to be specified for pro‐
261 grams that can unwind programs on multiple platforms.
262
264 libunwind-dynamic(3), libunwind-ia64(3), libunwind-ptrace(3), libun‐
265 wind-setjmp(3), unw_create_addr_space(3), unw_destroy_addr_space(3),
266 unw_flush_cache(3), unw_get_accessors(3), unw_get_fpreg(3),
267 unw_get_proc_info(3), unw_get_proc_name(3), unw_get_reg(3), unw_getcon‐
268 text(3), unw_init_local(3), unw_init_remote(3), unw_is_fpreg(3),
269 unw_is_signal_frame(3), unw_regname(3), unw_resume(3),
270 unw_set_caching_policy(3), unw_set_cache_size(3), unw_set_fpreg(3),
271 unw_set_reg(3), unw_step(3), unw_strerror(3), _U_dyn_register(3),
272 _U_dyn_cancel(3)
273
275 David Mosberger-Tang
276 Email: dmosberger@gmail.com
277 WWW: http://www.nongnu.org/libunwind/.
278Programming Library 29 August 2021 LIBUNWIND(3)