doc/libunwind.tex

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