2 .\" Manual page created with latex2man on Thu Aug 16 09:44:43 MDT 2007
3 .\" NOTE: This file is generated, DO NOT EDIT.
13 .TH "LIBUNWIND" "3" "16 August 2007" "Programming Library " "Programming Library "
16 \-\- a (mostly) platform\-independent unwind API
21 #include <libunwind.h>
25 unw_getcontext(unw_context_t *);
28 unw_init_local(unw_cursor_t *,
32 unw_init_remote(unw_cursor_t *,
37 unw_step(unw_cursor_t *);
40 unw_get_reg(unw_cursor_t *,
45 unw_get_fpreg(unw_cursor_t *,
50 unw_set_reg(unw_cursor_t *,
55 unw_set_fpreg(unw_cursor_t *,
60 unw_resume(unw_cursor_t *);
67 unw_create_addr_space(unw_accessors_t,
71 unw_destroy_addr_space(unw_addr_space_t);
74 unw_get_accessors(unw_addr_space_t);
77 unw_flush_cache(unw_addr_space_t,
82 unw_set_caching_policy(unw_addr_space_t,
83 unw_caching_policy_t);
86 const char *unw_regname(unw_regnum_t);
89 unw_get_proc_info(unw_cursor_t *,
93 unw_get_save_loc(unw_cursor_t *,
98 unw_is_fpreg(unw_regnum_t);
101 unw_is_signal_frame(unw_cursor_t *);
104 unw_get_proc_name(unw_cursor_t *,
111 _U_dyn_register(unw_dyn_info_t *);
114 _U_dyn_cancel(unw_dyn_info_t *);
121 is very easy to use when unwinding a stack from
122 within a running program. This is called \fIlocal\fP
124 you want to unwind the stack while executing in some function
126 In this function, you would call unw_getcontext()
127 to get a snapshot of the CPU registers (machine\-state). Then you
128 initialize an \fIunwind cursor\fP
129 based on this snapshot. This is
130 done with a call to unw_init_local().
131 The cursor now points
132 to the current frame, that is, the stack frame that corresponds to the
133 current activation of function F().
134 The unwind cursor can then
135 be moved ``up\&'' (towards earlier stack frames) by calling
137 By repeatedly calling this routine, you can
138 uncover the entire call\-chain that led to the activation of function
140 A positive return value from unw_step()
142 that there are more frames in the chain, zero indicates that the end
143 of the chain has been reached, and any negative value indicates that
144 some sort of error has occurred.
146 While it is not possible to directly move the unwind cursor in the
147 ``down\&'' direction (towards newer stack frames), this effect can be
148 achieved by making copies of an unwind cursor. For example, a program
149 that sometimes has to move ``down\&'' by one stack frame could maintain
150 two cursor variables: ``curr\&''
153 would be used as the current cursor and prev
155 as the ``previous frame\&'' cursor by copying the contents of curr
157 right before calling unw_step().
159 approach, the program could move one step ``down\&'' simply by copying
162 whenever that is necessary. In the most
163 extreme case, a program could maintain a separate cursor for each call
164 frame and that way it could move up and down the callframe\-chain at
167 Given an unwind cursor, it is possible to read and write the CPU
168 registers that were preserved for the current stack frame (as
169 identified by the cursor). Libunwind
170 provides several routines
171 for this purpose: unw_get_reg()
172 reads an integer (general)
173 register, unw_get_fpreg()
174 reads a floating\-point register,
176 writes an integer register, and
178 writes a floating\-point register. Note that,
179 by definition, only the \fIpreserved\fP
180 machine state can be accessed
181 during an unwind operation. Normally, this state consists of the
183 (``preserved\&'') registers. However, in some
184 special circumstances (e.g., in a signal handler trampoline), even the
186 (``scratch\&'') registers are preserved in the stack
187 frame and, in those cases, libunwind
188 will grant access to them
189 as well. The exact set of registers that can be accessed via the
190 cursor depends, of course, on the platform. However, there are two
191 registers that can be read on all platforms: the instruction pointer
192 (IP), sometimes also known as the ``program counter\&'', and the stack
193 pointer (SP). In libunwind,
194 these registers are identified by
195 the macros UNW_REG_IP
199 Besides just moving the unwind cursor and reading/writing saved
201 also provides the ability to resume
202 execution at an arbitrary stack frame. As you might guess, this is
203 useful for implementing non\-local gotos and the exception handling
204 needed by some high\-level languages such as Java. Resuming execution
205 with a particular stack frame simply requires calling
207 and passing the cursor identifying the target
208 frame as the only argument.
211 supports both local and remote unwinding
212 (the latter will be explained in the next section). However, if you
213 tell libunwind that your program only needs local unwinding, then a
214 special implementation can be selected which may run much faster than
215 the generic implementation which supports both kinds of unwinding. To
216 select this optimized version, simply define the macro
218 before including the headerfile
220 It is perfectly OK for a single program to
221 employ both local\-only and generic unwinding. That is, whether or not
223 is defined is a choice that each source\-file
224 (compilation\-unit) can make on its own. Independent of the setting(s)
226 you\&'ll always link the same library into
227 the program (normally \fB\-l\fPunwind).
230 that manages unwind\-info for dynamically
231 generated code is not affected by the setting of
234 If we put all of the above together, here is how we could use
236 to write a function ``show_backtrace()\&''
237 which prints a classic stack trace:
240 #define UNW_LOCAL_ONLY
241 #include <libunwind.h>
243 void show_backtrace (void) {
244 unw_cursor_t cursor; unw_context_t uc;
248 unw_init_local(&cursor, &uc);
249 while (unw_step(&cursor) > 0) {
250 unw_get_reg(&cursor, UNW_REG_IP, &ip);
251 unw_get_reg(&cursor, UNW_REG_SP, &sp);
252 printf ("ip = %lx, sp = %lx\\n", (long) ip, (long) sp);
261 can also be used to unwind a stack in a ``remote\&''
262 process. Here, ``remote\&'' may mean another process on the same
263 machine or even a process on a completely different machine from the
264 one that is running libunwind\&.
265 Remote unwinding is typically
266 used by debuggers and instruction\-set simulators, for example.
268 Before you can unwind a remote process, you need to create a new
269 address\-space object for that process. This is achieved with the
270 unw_create_addr_space()
271 routine. The routine takes two
272 arguments: a pointer to a set of \fIaccessor\fP
274 integer that specifies the byte\-order of the target process. The
275 accessor routines provide libunwind
277 communicate with the remote process. In particular, there are
278 callbacks to read and write the process\&'s memory, its registers, and
279 to access unwind information which may be needed by libunwind\&.
281 With the address space created, unwinding can be initiated by a call
282 to unw_init_remote().
283 This routine is very similar to
285 except that it takes an address\-space
286 object and an opaque pointer as arguments. The routine uses these
287 arguments to fetch the initial machine state. Libunwind
289 uses the opaque pointer on its own, but instead just passes it on to
290 the accessor (callback) routines. Typically, this pointer is used to
291 select, e.g., the thread within a process that is to be unwound.
293 Once a cursor has been initialized with unw_init_remote(),
294 unwinding works exactly like in the local case. That is, you can use
296 to move ``up\&'' in the call\-chain, read and write
297 registers, or resume execution at a particular stack frame by calling
300 .SH CROSS\-PLATFORM AND MULTI\-PLATFORM UNWINDING
304 has been designed to enable unwinding across
305 platforms (architectures). Indeed, a single program can use
307 to unwind an arbitrary number of target platforms,
308 all at the same time!
310 We call the machine that is running libunwind
312 and the machine that is running the process being unwound the
314 If the host and the target platform are the same, we
316 unwinding. If they differ, we call it
317 \fIcross\-platform\fP
320 The principle behind supporting native, cross\-platform, and
321 multi\-platform unwinding is very simple: for native unwinding, a
322 program includes <libunwind.h>
323 and uses the linker switch
325 For cross\-platform unwinding, a program
326 includes <libunwind\-PLAT\&.h>
328 switch \fB\-l\fPunwind\-PLAT,
331 of the target platform (e.g., ia64
332 for IA\-64, hppa\-elf
333 for ELF\-based HP PA\-RISC, or x86
334 for 80386). Multi\-platform
335 unwinding works exactly like cross\-platform unwinding, the only
336 limitation is that a single source file (compilation unit) can include
337 at most one libunwind
338 header file. In other words, the
339 platform\-specific support for each supported target needs to be
340 isolated in separate source files\-\-\-a limitation that shouldn\&'t be an
343 Note that, by definition, local unwinding is possible only for the
344 native case. Attempting to call, e.g., unw_local_init()
346 targeting a cross\-platform will result in a link\-time error
347 (unresolved references).
349 .SH THREAD\- AND SIGNAL\-SAFETY
353 routines are thread\-safe. What this means is
354 that multiple threads may use libunwind
356 However, any given cursor may be accessed by only one thread at
359 To ensure thread\-safety, some libunwind
361 use locking. Such routines \fImust not\fP
362 be called from signal
363 handlers (directly or indirectly) and are therefore \fInot\fP
364 signal\-safe. The manual page for each libunwind
366 identifies whether or not it is signal\-safe, but as a general rule,
367 any routine that may be needed for \fIlocal\fP
369 signal\-safe (e.g., unw_step()
370 for local unwinding is
371 signal\-safe). For remote\-unwinding, \fInone\fP
374 routines are guaranteed to be signal\-safe.
376 .SH UNWINDING THROUGH DYNAMICALLY GENERATED CODE
380 provides the routines _U_dyn_register()
383 to register/cancel the information required to
384 unwind through code that has been generated at runtime (e.g., by a
385 just\-in\-time (JIT) compiler). It is important to register the
386 information for \fIall\fP
387 dynamically generated code because
388 otherwise, a debugger may not be able to function properly or
389 high\-level language exception handling may not work as expected.
391 The interface for registering and canceling dynamic unwind info has
392 been designed for maximum efficiency, so as to minimize the
393 performance impact on JIT\-compilers. In particular, both routines are
394 guaranteed to execute in ``constant time\&'' (O(1)) and the
395 data\-structure encapsulating the dynamic unwind info has been designed
396 to facilitate sharing, such that similar procedures can share much of
397 the underlying information.
399 For more information on the libunwind
400 support for dynamically
401 generated code, see libunwind\-dynamic(3)\&.
403 .SH CACHING OF UNWIND INFO
406 To speed up execution, libunwind
407 may aggressively cache the
408 information it needs to perform unwinding. If a process changes
409 during its lifetime, this creates a risk of libunwind
411 stale data. For example, this would happen if libunwind
413 to cache information about a shared library which later on gets
414 unloaded (e.g., via \fIdlclose\fP(3)).
416 To prevent the risk of using stale data, libunwind
418 facilities: first, it is possible to flush the cached information
419 associated with a specific address range in the target process (or the
420 entire address space, if desired). This functionality is provided by
422 The second facility is provided by
423 unw_set_caching_policy(),
425 select the exact caching policy in use for a given address\-space
426 object. In particular, by selecting the policy
428 it is possible to turn off caching
429 completely, therefore eliminating the risk of stale data alltogether
430 (at the cost of slower execution). By default, caching is enabled for
431 local unwinding only.
438 Headerfile to include for native (same
442 Headerfile to include when
443 the unwind target runs on platform PLAT\&.
444 For example, to unwind
445 an IA\-64 program, the header file libunwind\-ia64.h
450 Linker\-switch to add when building a
451 program that does native (same platform) unwinding.
453 \fB\-l\fPunwind\-PLAT
454 Linker\-switch to add when
455 building a program that unwinds a program on platform PLAT\&.
456 For example, to (cross\-)unwind an IA\-64 program, the linker switch
458 should be added. Note: multiple such switches
459 may need to be specified for programs that can unwind programs on
465 libunwind\-dynamic(3),
467 libunwind\-ptrace(3),
468 libunwind\-setjmp(3),
469 unw_create_addr_space(3),
470 unw_destroy_addr_space(3),
472 unw_get_accessors(3),
474 unw_get_proc_info(3),
475 unw_get_proc_name(3),
481 unw_is_signal_frame(3),
484 unw_set_caching_policy(3),
495 David Mosberger\-Tang
497 Email: \fBdmosberger@gmail.com\fP
499 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
500 .\" NOTE: This file is generated, DO NOT EDIT.