1 \documentclass{article} 2 \usepackage[fancyhdr,pdf]{latex2man} 3 4 \input{common.tex} 5 6 \begin{document} 7 8 \begin{Name}{3}{libunwind}{David Mosberger-Tang}{Programming Library}{Introduction to libunwind}libunwind -- a (mostly) platform-independent unwind API 9 \end{Name} 10 11 \section{Synopsis} 12 13 \File{\#include $<$libunwind.h$>$}\\ 14 15 \noindent 16 \Type{int} \Func{unw\_getcontext}(\Type{unw\_context\_t~*});\\ 17 \noindent 18 \Type{int} \Func{unw\_init\_local}(\Type{unw\_cursor\_t~*}, \Type{unw\_context\_t~*});\\ 19 \noindent 20 \Type{int} \Func{unw\_init\_remote}(\Type{unw\_cursor\_t~*}, \Type{unw\_addr\_space\_t}, \Type{void~*});\\ 21 \noindent 22 \Type{int} \Func{unw\_step}(\Type{unw\_cursor\_t~*});\\ 23 \noindent 24 \Type{int} \Func{unw\_get\_reg}(\Type{unw\_cursor\_t~*}, \Type{unw\_regnum\_t}, \Type{unw\_word\_t~*});\\ 25 \noindent 26 \Type{int} \Func{unw\_get\_fpreg}(\Type{unw\_cursor\_t~*}, \Type{unw\_regnum\_t}, \Type{unw\_fpreg\_t~*});\\ 27 \noindent 28 \Type{int} \Func{unw\_set\_reg}(\Type{unw\_cursor\_t~*}, \Type{unw\_regnum\_t}, \Type{unw\_word\_t});\\ 29 \noindent 30 \Type{int} \Func{unw\_set\_fpreg}(\Type{unw\_cursor\_t~*}, \Type{unw\_regnum\_t}, \Type{unw\_fpreg\_t});\\ 31 \noindent 32 \Type{int} \Func{unw\_resume}(\Type{unw\_cursor\_t~*});\\ 33 34 \noindent 35 \Type{unw\_addr\_space\_t} \Var{unw\_local\_addr\_space};\\ 36 \noindent 37 \Type{unw\_addr\_space\_t} \Func{unw\_create\_addr\_space}(\Type{unw\_accessors\_t}, \Type{int});\\ 38 \noindent 39 \Type{void} \Func{unw\_destroy\_addr\_space}(\Type{unw\_addr\_space\_t});\\ 40 \noindent 41 \Type{unw\_accessors\_t} \Func{unw\_get\_accessors}(\Type{unw\_addr\_space\_t});\\ 42 \noindent 43 \Type{void} \Func{unw\_flush\_cache}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{unw\_word\_t});\\ 44 \noindent 45 \Type{int} \Func{unw\_set\_caching\_policy}(\Type{unw\_addr\_space\_t}, \Type{unw\_caching\_policy\_t});\\ 46 47 \noindent 48 \Type{const char *}\Func{unw\_regname}(\Type{unw\_regnum\_t});\\ 49 \noindent 50 \Type{int} \Func{unw\_get\_proc\_info}(\Type{unw\_cursor\_t~*}, \Type{unw\_proc\_info\_t~*});\\ 51 \noindent 52 \Type{int} \Func{unw\_get\_save\_loc}(\Type{unw\_cursor\_t~*}, \Type{int}, \Type{unw\_save\_loc\_t~*});\\ 53 \noindent 54 \Type{int} \Func{unw\_is\_fpreg}(\Type{unw\_regnum\_t});\\ 55 \Type{int} \Func{unw\_is\_signal\_frame}(\Type{unw\_cursor\_t~*});\\ 56 \noindent 57 \Type{int} \Func{unw\_get\_proc\_name}(\Type{unw\_cursor\_t~*}, \Type{char~*}, \Type{size\_t}, \Type{unw\_word\_t~*});\\ 58 59 \noindent 60 \Type{void} \Func{\_U\_dyn\_register}(\Type{unw\_dyn\_info\_t~*});\\ 61 \noindent 62 \Type{void} \Func{\_U\_dyn\_cancel}(\Type{unw\_dyn\_info\_t~*});\\ 63 64 \section{Local Unwinding} 65 66 \Prog{Libunwind} is very easy to use when unwinding a stack from 67 within a running program. This is called \emph{local} unwinding. Say 68 you want to unwind the stack while executing in some function 69 \Func{F}(). In this function, you would call \Func{unw\_getcontext}() 70 to get a snapshot of the CPU registers (machine-state). Then you 71 initialize an \emph{unwind~cursor} based on this snapshot. This is 72 done with a call to \Func{unw\_init\_local}(). The cursor now points 73 to the current frame, that is, the stack frame that corresponds to the 74 current activation of function \Func{F}(). The unwind cursor can then 75 be moved ``up'' (towards earlier stack frames) by calling 76 \Func{unw\_step}(). By repeatedly calling this routine, you can 77 uncover the entire call-chain that led to the activation of function 78 \Func{F}(). A positive return value from \Func{unw\_step}() indicates 79 that there are more frames in the chain, zero indicates that the end 80 of the chain has been reached, and any negative value indicates that 81 some sort of error has occurred. 82 83 While it is not possible to directly move the unwind cursor in the 84 ``down'' direction (towards newer stack frames), this effect can be 85 achieved by making copies of an unwind cursor. For example, a program 86 that sometimes has to move ``down'' by one stack frame could maintain 87 two cursor variables: ``\Var{curr}'' and ``\Var{prev}''. The former 88 would be used as the current cursor and \Var{prev} would be maintained 89 as the ``previous frame'' cursor by copying the contents of \Var{curr} 90 to \Var{prev} right before calling \Func{unw\_step}(). With this 91 approach, the program could move one step ``down'' simply by copying 92 back \Var{prev} to \Var{curr} whenever that is necessary. In the most 93 extreme case, a program could maintain a separate cursor for each call 94 frame and that way it could move up and down the callframe-chain at 95 will. 96 97 Given an unwind cursor, it is possible to read and write the CPU 98 registers that were preserved for the current stack frame (as 99 identified by the cursor). \Prog{Libunwind} provides several routines 100 for this purpose: \Func{unw\_get\_reg}() reads an integer (general) 101 register, \Func{unw\_get\_fpreg}() reads a floating-point register, 102 \Func{unw\_set\_reg}() writes an integer register, and 103 \Func{unw\_set\_fpreg}() writes a floating-point register. Note that, 104 by definition, only the \emph{preserved} machine state can be accessed 105 during an unwind operation. Normally, this state consists of the 106 \emph{callee-saved} (``preserved'') registers. However, in some 107 special circumstances (e.g., in a signal handler trampoline), even the 108 \emph{caller-saved} (``scratch'') registers are preserved in the stack 109 frame and, in those cases, \Prog{libunwind} will grant access to them 110 as well. The exact set of registers that can be accessed via the 111 cursor depends, of course, on the platform. However, there are two 112 registers that can be read on all platforms: the instruction pointer 113 (IP), sometimes also known as the ``program counter'', and the stack 114 pointer (SP). In \Prog{libunwind}, these registers are identified by 115 the macros \Const{UNW\_REG\_IP} and \Const{UNW\_REG\_SP}, 116 respectively. 117 118 Besides just moving the unwind cursor and reading/writing saved 119 registers, \Prog{libunwind} also provides the ability to resume 120 execution at an arbitrary stack frame. As you might guess, this is 121 useful for implementing non-local gotos and the exception handling 122 needed by some high-level languages such as Java. Resuming execution 123 with a particular stack frame simply requires calling 124 \Func{unw\_resume}() and passing the cursor identifying the target 125 frame as the only argument. 126 127 Normally, \Prog{libunwind} supports both local and remote unwinding 128 (the latter will be explained in the next section). However, if you 129 tell libunwind that your program only needs local unwinding, then a 130 special implementation can be selected which may run much faster than 131 the generic implementation which supports both kinds of unwinding. To 132 select this optimized version, simply define the macro 133 \Const{UNW\_LOCAL\_ONLY} before including the headerfile 134 \File{$<$libunwind.h$>$}. It is perfectly OK for a single program to 135 employ both local-only and generic unwinding. That is, whether or not 136 \Const{UNW\_LOCAL\_ONLY} is defined is a choice that each source-file 137 (compilation-unit) can make on its own. Independent of the setting(s) 138 of \Const{UNW\_LOCAL\_ONLY}, you'll always link the same library into 139 the program (normally \Opt{-l}\File{unwind}). Furthermore, the 140 portion of \Prog{libunwind} that manages unwind-info for dynamically 141 generated code is not affected by the setting of 142 \Const{UNW\_LOCAL\_ONLY}. 143 144 If we put all of the above together, here is how we could use 145 \Prog{libunwind} to write a function ``\Func{show\_backtrace}()'' 146 which prints a classic stack trace: 147 148 \begin{verbatim} 149 #define UNW_LOCAL_ONLY 150 #include <libunwind.h> 151 152 void show_backtrace (void) { 153 unw_cursor_t cursor; unw_context_t uc; 154 unw_word_t ip, sp; 155 156 unw_getcontext(&uc); 157 unw_init_local(&cursor, &uc); 158 while (unw_step(&cursor) > 0) { 159 unw_get_reg(&cursor, UNW_REG_IP, &ip); 160 unw_get_reg(&cursor, UNW_REG_SP, &sp); 161 printf ("ip = %lx, sp = %lx\n", (long) ip, (long) sp); 162 } 163 } 164 \end{verbatim} 165 166 167 \section{Remote Unwinding} 168 169 \Prog{Libunwind} can also be used to unwind a stack in a ``remote'' 170 process. Here, ``remote'' may mean another process on the same 171 machine or even a process on a completely different machine from the 172 one that is running \Prog{libunwind}. Remote unwinding is typically 173 used by debuggers and instruction-set simulators, for example. 174 175 Before you can unwind a remote process, you need to create a new 176 address-space object for that process. This is achieved with the 177 \Func{unw\_create\_addr\_space}() routine. The routine takes two 178 arguments: a pointer to a set of \emph{accessor} routines and an 179 integer that specifies the byte-order of the target process. The 180 accessor routines provide \Func{libunwind} with the means to 181 communicate with the remote process. In particular, there are 182 callbacks to read and write the process's memory, its registers, and 183 to access unwind information which may be needed by \Func{libunwind}. 184 185 With the address space created, unwinding can be initiated by a call 186 to \Func{unw\_init\_remote}(). This routine is very similar to 187 \Func{unw\_init\_local}(), except that it takes an address-space 188 object and an opaque pointer as arguments. The routine uses these 189 arguments to fetch the initial machine state. \Prog{Libunwind} never 190 uses the opaque pointer on its own, but instead just passes it on to 191 the accessor (callback) routines. Typically, this pointer is used to 192 select, e.g., the thread within a process that is to be unwound. 193 194 Once a cursor has been initialized with \Func{unw\_init\_remote}(), 195 unwinding works exactly like in the local case. That is, you can use 196 \Func{unw\_step}() to move ``up'' in the call-chain, read and write 197 registers, or resume execution at a particular stack frame by calling 198 \Func{unw\_resume}. 199 200 201 \section{Cross-platform and Multi-platform Unwinding} 202 203 \Prog{Libunwind} has been designed to enable unwinding across 204 platforms (architectures). Indeed, a single program can use 205 \Prog{libunwind} to unwind an arbitrary number of target platforms, 206 all at the same time! 207 208 We call the machine that is running \Prog{libunwind} the \emph{host} 209 and the machine that is running the process being unwound the 210 \emph{target}. If the host and the target platform are the same, we 211 call it \emph{native} unwinding. If they differ, we call it 212 \emph{cross-platform} unwinding. 213 214 The principle behind supporting native, cross-platform, and 215 multi-platform unwinding is very simple: for native unwinding, a 216 program includes \File{$<$libunwind.h$>$} and uses the linker switch 217 \Opt{-l}\File{unwind}. For cross-platform unwinding, a program 218 includes \File{$<$libunwind-}\Var{PLAT}\File{.h$>$} and uses the linker 219 switch \Opt{-l}\File{unwind-}\Var{PLAT}, where \Var{PLAT} is the name 220 of the target platform (e.g., \File{ia64} for IA-64, \File{hppa-elf} 221 for ELF-based HP PA-RISC, or \File{x86} for 80386). Multi-platform 222 unwinding works exactly like cross-platform unwinding, the only 223 limitation is that a single source file (compilation unit) can include 224 at most one \Prog{libunwind} header file. In other words, the 225 platform-specific support for each supported target needs to be 226 isolated in separate source files---a limitation that shouldn't be an 227 issue in practice. 228 229 Note that, by definition, local unwinding is possible only for the 230 native case. Attempting to call, e.g., \Func{unw\_local\_init}() when 231 targeting a cross-platform will result in a link-time error 232 (unresolved references). 233 234 235 \section{Thread- and Signal-Safety} 236 237 238 All \Prog{libunwind} routines are thread-safe. What this means is 239 that multiple threads may use \Prog{libunwind} simulatenously. 240 However, any given cursor may be accessed by only one thread at 241 any given time. 242 243 To ensure thread-safety, some \Prog{libunwind} routines may have to 244 use locking. Such routines \emph{must~not} be called from signal 245 handlers (directly or indirectly) and are therefore \emph{not} 246 signal-safe. The manual page for each \Prog{libunwind} routine 247 identifies whether or not it is signal-safe, but as a general rule, 248 any routine that may be needed for \emph{local} unwinding is 249 signal-safe (e.g., \Func{unw\_step}() for local unwinding is 250 signal-safe). For remote-unwinding, \emph{none} of the 251 \Prog{libunwind} routines are guaranteed to be signal-safe. 252 253 254 \section{Unwinding Through Dynamically Generated Code} 255 256 \Func{Libunwind} provides the routines \Func{\_U\_dyn\_register}() and 257 \Func{\_U\_dyn\_cancel}() to register/cancel the information required to 258 unwind through code that has been generated at runtime (e.g., by a 259 just-in-time (JIT) compiler). It is important to register the 260 information for \emph{all} dynamically generated code because 261 otherwise, a debugger may not be able to function properly or 262 high-level language exception handling may not work as expected. 263 264 The interface for registering and canceling dynamic unwind info has 265 been designed for maximum efficiency, so as to minimize the 266 performance impact on JIT-compilers. In particular, both routines are 267 guaranteed to execute in ``constant time'' (O(1)) and the 268 data-structure encapsulating the dynamic unwind info has been designed 269 to facilitate sharing, such that similar procedures can share much of 270 the underlying information. 271 272 For more information on the \Prog{libunwind} support for dynamically 273 generated code, see \SeeAlso{libunwind-dynamic(3)}. 274 275 276 \section{Caching of Unwind Info} 277 278 To speed up execution, \Prog{libunwind} may aggressively cache the 279 information it needs to perform unwinding. If a process changes 280 during its lifetime, this creates a risk of \Prog{libunwind} using 281 stale data. For example, this would happen if \Prog{libunwind} were 282 to cache information about a shared library which later on gets 283 unloaded (e.g., via \Cmd{dlclose}{3}). 284 285 To prevent the risk of using stale data, \Prog{libunwind} provides two 286 facilities: first, it is possible to flush the cached information 287 associated with a specific address range in the target process (or the 288 entire address space, if desired). This functionality is provided by 289 \Func{unw\_flush\_cache}(). The second facility is provided by 290 \Func{unw\_set\_caching\_policy}(), which lets a program 291 select the exact caching policy in use for a given address-space 292 object. In particular, by selecting the policy 293 \Const{UNW\_CACHE\_NONE}, it is possible to turn off caching 294 completely, therefore eliminating the risk of stale data alltogether 295 (at the cost of slower execution). By default, caching is enabled for 296 local unwinding only. 297 298 299 \section{Files} 300 301 \begin{Description} 302 \item[\File{libunwind.h}] Headerfile to include for native (same 303 platform) unwinding. 304 \item[\File{libunwind-}\Var{PLAT}\File{.h}] Headerfile to include when 305 the unwind target runs on platform \Var{PLAT}. For example, to unwind 306 an IA-64 program, the header file \File{libunwind-ia64.h} should be 307 included. 308 \item[\Opt{-l}\File{unwind}] Linker-switch to add when building a 309 program that does native (same platform) unwinding. 310 \item[\Opt{-l}\File{unwind-}\Var{PLAT}] Linker-switch to add when 311 building a program that unwinds a program on platform \Var{PLAT}. 312 For example, to (cross-)unwind an IA-64 program, the linker switch 313 \File{-lunwind-ia64} should be added. Note: multiple such switches 314 may need to be specified for programs that can unwind programs on 315 multiple platforms. 316 \end{Description} 317 318 \section{See Also} 319 320 \SeeAlso{libunwind-dynamic(3)}, 321 \SeeAlso{libunwind-ia64(3)}, 322 \SeeAlso{libunwind-ptrace(3)}, 323 \SeeAlso{libunwind-setjmp(3)}, 324 \SeeAlso{unw\_create\_addr\_space(3)}, 325 \SeeAlso{unw\_destroy\_addr\_space(3)}, 326 \SeeAlso{unw\_flush\_cache(3)}, 327 \SeeAlso{unw\_get\_accessors(3)}, 328 \SeeAlso{unw\_get\_fpreg(3)}, 329 \SeeAlso{unw\_get\_proc\_info(3)}, 330 \SeeAlso{unw\_get\_proc\_name(3)}, 331 \SeeAlso{unw\_get\_reg(3)}, 332 \SeeAlso{unw\_getcontext(3)}, 333 \SeeAlso{unw\_init\_local(3)}, 334 \SeeAlso{unw\_init\_remote(3)}, 335 \SeeAlso{unw\_is\_fpreg(3)}, 336 \SeeAlso{unw\_is\_signal\_frame(3)}, 337 \SeeAlso{unw\_regname(3)}, 338 \SeeAlso{unw\_resume(3)}, 339 \SeeAlso{unw\_set\_caching\_policy(3)}, 340 \SeeAlso{unw\_set\_fpreg(3)}, 341 \SeeAlso{unw\_set\_reg(3)}, 342 \SeeAlso{unw\_step(3)}, 343 \SeeAlso{unw\_strerror(3)}, 344 \SeeAlso{\_U\_dyn\_register(3)}, 345 \SeeAlso{\_U\_dyn\_cancel(3)} 346 347 \section{Author} 348 349 \noindent 350 David Mosberger-Tang\\ 351 Email: \Email{dmosberger (a] gmail.com}\\ 352 WWW: \URL{http://www.nongnu.org/libunwind/}. 353 \LatexManEnd 354 355 \end{document} 356