1LIBUNWIND(3)                 Programming Library                  LIBUNWIND(3)
2
3
4

NAME

6       libunwind -- a (mostly) platform-independent unwind API
7

SYNOPSIS

9       #include <libunwind.h>
10
11       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
21       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
28       const char *unw_regname(unw_regnum_t);
29       int unw_get_proc_info(unw_cursor_t *, unw_proc_info_t *);
30       int unw_get_save_loc(unw_cursor_t *, int, unw_save_loc_t *);
31       int unw_is_fpreg(unw_regnum_t);
32       int unw_is_signal_frame(unw_cursor_t *);
33       int unw_get_proc_name(unw_cursor_t *, char *, size_t, unw_word_t *);
34
35       void _U_dyn_register(unw_dyn_info_t *);
36       void _U_dyn_cancel(unw_dyn_info_t *);
37

LOCAL UNWINDING

39       Libunwind is very easy to use when unwinding a stack from within a run‐
40       ning program. This is called local unwinding. Say you  want  to  unwind
41       the  stack while executing in some function F().  In this function, you
42       would call unw_getcontext() to get a  snapshot  of  the  CPU  registers
43       (machine-state).  Then  you  initialize  an unwind cursor based on this
44       snapshot. This is done with a call to unw_init_local().  The cursor now
45       points  to the current frame, that is, the stack frame that corresponds
46       to the current activation of function F().  The unwind cursor can  then
47       be  moved  ``up'' (towards earlier stack frames) by calling unw_step().
48       By  repeatedly  calling  this  routine,  you  can  uncover  the  entire
49       call-chain  that  led  to  the  activation of function F().  A positive
50       return value from unw_step() indicates that there are  more  frames  in
51       the  chain,  zero indicates that the end of the chain has been reached,
52       and any negative value indicates that some sort of error has occurred.
53
54       While it is not possible to directly move  the  unwind  cursor  in  the
55       ``down''  direction  (towards  newer  stack frames), this effect can be
56       achieved by making copies of an unwind cursor. For example,  a  program
57       that  sometimes  has to move ``down'' by one stack frame could maintain
58       two cursor variables: ``curr'' and ``prev''.  The former would be  used
59       as  the  current  cursor and prev would be maintained as the ``previous
60       frame'' cursor by copying the contents of curr  to  prev  right  before
61       calling  unw_step().   With  this  approach, the program could move one
62       step ``down'' simply by copying back prev to curr whenever that is nec‐
63       essary.  In  the most extreme case, a program could maintain a separate
64       cursor for each call frame and that way it could move up and  down  the
65       callframe-chain at will.
66
67       Given an unwind cursor, it is possible to read and write the CPU regis‐
68       ters that were preserved for the current stack frame (as identified  by
69       the  cursor).  Libunwind  provides  several  routines for this purpose:
70       unw_get_reg() reads  an  integer  (general)  register,  unw_get_fpreg()
71       reads a floating-point register, unw_set_reg() writes an integer regis‐
72       ter, and unw_set_fpreg() writes a floating-point register.  Note  that,
73       by  definition, only the preserved machine state can be accessed during
74       an unwind operation. Normally, this state consists of the  callee-saved
75       (``preserved'')  registers.  However,  in  some  special  circumstances
76       (e.g.,  in  a  signal  handler  trampoline),  even   the   caller-saved
77       (``scratch'')  registers are preserved in the stack frame and, in those
78       cases, libunwind will grant access to them as well. The  exact  set  of
79       registers  that  can  be accessed via the cursor depends, of course, on
80       the platform. However, there are two registers that can be read on  all
81       platforms:  the  instruction  pointer (IP), sometimes also known as the
82       ``program counter'', and the stack pointer (SP).  In  libunwind,  these
83       registers  are  identified  by  the  macros  UNW_REG_IP and UNW_REG_SP,
84       respectively.
85
86       Besides just moving the unwind cursor and reading/writing saved  regis‐
87       ters,  libunwind  also  provides  the ability to resume execution at an
88       arbitrary stack frame. As you might guess, this is  useful  for  imple‐
89       menting  non-local  gotos  and  the  exception  handling needed by some
90       high-level languages such as Java. Resuming execution with a particular
91       stack frame simply requires calling unw_resume() and passing the cursor
92       identifying the target frame as the only argument.
93
94       Normally, libunwind supports both local and remote unwinding (the  lat‐
95       ter will be explained in the next section). However, if you tell libun‐
96       wind that your program only  needs  local  unwinding,  then  a  special
97       implementation  can  be  selected  which  may  run much faster than the
98       generic implementation which  supports  both  kinds  of  unwinding.  To
99       select  this  optimized version, simply define the macro UNW_LOCAL_ONLY
100       before including the headerfile <libunwind.h>.  It is perfectly OK  for
101       a  single program to employ both local-only and generic unwinding. That
102       is, whether or not UNW_LOCAL_ONLY is defined  is  a  choice  that  each
103       source-file  (compilation-unit) can make on its own. Independent of the
104       setting(s) of UNW_LOCAL_ONLY, you'll always link the same library  into
105       the program (normally -lunwind).  Furthermore, the portion of libunwind
106       that manages unwind-info for dynamically generated code is not affected
107       by the setting of UNW_LOCAL_ONLY.
108
109       If we put all of the above together, here is how we could use libunwind
110       to write a function ``show_backtrace()'' which prints a  classic  stack
111       trace:
112
113       #define UNW_LOCAL_ONLY
114       #include <libunwind.h>
115
116       void show_backtrace (void) {
117         unw_cursor_t cursor; unw_context_t uc;
118         unw_word_t ip, sp;
119
120         unw_getcontext(&uc);
121         unw_init_local(&cursor, &uc);
122         while (unw_step(&cursor) > 0) {
123           unw_get_reg(&cursor, UNW_REG_IP, &ip);
124           unw_get_reg(&cursor, UNW_REG_SP, &sp);
125           printf ("ip = %lx, sp = %lx\n", (long) ip, (long) sp);
126         }
127       }
128
129

REMOTE UNWINDING

131       Libunwind  can  also be used to unwind a stack in a ``remote'' process.
132       Here, ``remote'' may mean another process on the same machine or even a
133       process  on a completely different machine from the one that is running
134       libunwind.   Remote  unwinding  is  typically  used  by  debuggers  and
135       instruction-set simulators, for example.
136
137       Before  you  can  unwind  a  remote  process,  you need to create a new
138       address-space object for  that  process.  This  is  achieved  with  the
139       unw_create_addr_space()  routine.  The  routine  takes two arguments: a
140       pointer to a set of accessor routines and an integer that specifies the
141       byte-order  of the target process. The accessor routines provide libun‐
142       wind with the means to communicate with the remote process. In particu‐
143       lar,  there  are  callbacks to read and write the process's memory, its
144       registers, and to access unwind information  which  may  be  needed  by
145       libunwind.
146
147       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
151       machine  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
156       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

CROSS-PLATFORM AND MULTI-PLATFORM UNWINDING

162       Libunwind  has  been  designed  to  enable  unwinding  across platforms
163       (architectures). Indeed, a single program can use libunwind  to  unwind
164       an arbitrary number of target platforms, all at the same time!
165
166       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
171       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
178       unwinding,  the  only limitation is that a single source file (compila‐
179       tion unit) can include at most one  libunwind  header  file.  In  other
180       words, the platform-specific support for each supported target needs to
181       be isolated in separate source files---a limitation that  shouldn't  be
182       an issue in practice.
183
184       Note  that,  by  definition,  local  unwinding is possible only for the
185       native case. Attempting to call, e.g., unw_local_init() when  targeting
186       a  cross-platform  will  result in a link-time error (unresolved refer‐
187       ences).
188

THREAD- AND SIGNAL-SAFETY

190       All libunwind routines are thread-safe. What this means is that  multi‐
191       ple  threads may use libunwind simulatenously.  However, any given cur‐
192       sor may be accessed by only one thread at any given time.
193
194       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

UNWINDING THROUGH DYNAMICALLY GENERATED CODE

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
210       expected.
211
212       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
220       For more information on the libunwind support for dynamically generated
221       code, see libunwind-dynamic(3).
222

CACHING OF UNWIND INFO

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
230       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
233       address   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
237       selecting the policy UNW_CACHE_NONE, it is possible to turn off caching
238       completely, therefore eliminating the risk of  stale  data  alltogether
239       (at  the  cost of slower execution). By default, caching is enabled for
240       local unwinding only.
241

FILES

243       libunwind.h
244               Headerfile to include for native (same platform) unwinding.
245
246       libunwind-PLAT.h
247               Headerfile to include when the unwind target runs  on  platform
248              PLAT.   For example, to unwind an IA-64 program, the header file
249              libunwind-ia64.h should be included.
250
251       -lunwind
252               Linker-switch to add when building a program that  does  native
253              (same platform) unwinding.
254
255       -lunwind-PLAT
256               Linker-switch  to  add  when  building a program that unwinds a
257              program on platform PLAT.  For  example,  to  (cross-)unwind  an
258              IA-64  program, the linker switch -lunwind-ia64 should be added.
259              Note: multiple such switches may need to be specified  for  pro‐
260              grams that can unwind programs on multiple platforms.
261

SEE ALSO

263       libunwind-dynamic(3),  libunwind-ia64(3),  libunwind-ptrace(3),  libun‐
264       wind-setjmp(3),  unw_create_addr_space(3),   unw_destroy_addr_space(3),
265       unw_flush_cache(3),       unw_get_accessors(3),       unw_get_fpreg(3),
266       unw_get_proc_info(3), unw_get_proc_name(3), unw_get_reg(3), unw_getcon‐
267       text(3),    unw_init_local(3),   unw_init_remote(3),   unw_is_fpreg(3),
268       unw_is_signal_frame(3),         unw_regname(3),          unw_resume(3),
269       unw_set_caching_policy(3),       unw_set_fpreg(3),      unw_set_reg(3),
270       unw_step(3), unw_strerror(3), _U_dyn_register(3), _U_dyn_cancel(3)
271

AUTHOR

273       David Mosberger-Tang
274       Email: dmosberger@gmail.com
275       WWW: http://www.nongnu.org/libunwind/.
276
277
278
279Programming Library             16 August 2007                    LIBUNWIND(3)
Impressum