doc/libunwind.man

   1 '\" t
   2 .\" Manual page created with latex2man on Thu Aug 16 09:44:43 MDT 2007
   3 .\" NOTE: This file is generated, DO NOT EDIT.
   4 .de Vb
   5 .ft CW
   6 .nf
   7 ..
   8 .de Ve
   9 .ft R
  10
  11 .fi
  12 ..
  13 .TH "LIBUNWIND" "3" "16 August 2007" "Programming Library " "Programming Library "
  14 .SH NAME
  15 libunwind
  16 \-\- a (mostly) platform\-independent unwind API
  17 .PP
  18 .SH SYNOPSIS
  19
  20 .PP
  21 #include <libunwind.h>
  22 .br
  23 .PP
  24 int
  25 unw_getcontext(unw_context_t *);
  26 .br
  27 int
  28 unw_init_local(unw_cursor_t *,
  29 unw_context_t *);
  30 .br
  31 int
  32 unw_init_remote(unw_cursor_t *,
  33 unw_addr_space_t,
  34 void *);
  35 .br
  36 int
  37 unw_step(unw_cursor_t *);
  38 .br
  39 int
  40 unw_get_reg(unw_cursor_t *,
  41 unw_regnum_t,
  42 unw_word_t *);
  43 .br
  44 int
  45 unw_get_fpreg(unw_cursor_t *,
  46 unw_regnum_t,
  47 unw_fpreg_t *);
  48 .br
  49 int
  50 unw_set_reg(unw_cursor_t *,
  51 unw_regnum_t,
  52 unw_word_t);
  53 .br
  54 int
  55 unw_set_fpreg(unw_cursor_t *,
  56 unw_regnum_t,
  57 unw_fpreg_t);
  58 .br
  59 int
  60 unw_resume(unw_cursor_t *);
  61 .br
  62 .PP
  63 unw_addr_space_t
  64 unw_local_addr_space;
  65 .br
  66 unw_addr_space_t
  67 unw_create_addr_space(unw_accessors_t,
  68 int);
  69 .br
  70 void
  71 unw_destroy_addr_space(unw_addr_space_t);
  72 .br
  73 unw_accessors_t
  74 unw_get_accessors(unw_addr_space_t);
  75 .br
  76 void
  77 unw_flush_cache(unw_addr_space_t,
  78 unw_word_t,
  79 unw_word_t);
  80 .br
  81 int
  82 unw_set_caching_policy(unw_addr_space_t,
  83 unw_caching_policy_t);
  84 .br
  85 .PP
  86 const char *unw_regname(unw_regnum_t);
  87 .br
  88 int
  89 unw_get_proc_info(unw_cursor_t *,
  90 unw_proc_info_t *);
  91 .br
  92 int
  93 unw_get_save_loc(unw_cursor_t *,
  94 int,
  95 unw_save_loc_t *);
  96 .br
  97 int
  98 unw_is_fpreg(unw_regnum_t);
  99 .br
 100 int
 101 unw_is_signal_frame(unw_cursor_t *);
 102 .br
 103 int
 104 unw_get_proc_name(unw_cursor_t *,
 105 char *,
 106 size_t,
 107 unw_word_t *);
 108 .br
 109 .PP
 110 void
 111 _U_dyn_register(unw_dyn_info_t *);
 112 .br
 113 void
 114 _U_dyn_cancel(unw_dyn_info_t *);
 115 .br
 116 .PP
 117 .SH LOCAL UNWINDING
 118
 119 .PP
 120 Libunwind
 121 is very easy to use when unwinding a stack from
 122 within a running program. This is called \fIlocal\fP
 123 unwinding. Say
 124 you want to unwind the stack while executing in some function
 125 F().
 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
 136 unw_step().
 137 By repeatedly calling this routine, you can
 138 uncover the entire call\-chain that led to the activation of function
 139 F().
 140 A positive return value from unw_step()
 141 indicates
 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.
 145 .PP
 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\&''
 151 and ``prev\&''\&.
 152 The former
 153 would be used as the current cursor and prev
 154 would be maintained
 155 as the ``previous frame\&'' cursor by copying the contents of curr
 156 to prev
 157 right before calling unw_step().
 158 With this
 159 approach, the program could move one step ``down\&'' simply by copying
 160 back prev
 161 to curr
 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
 165 will.
 166 .PP
 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,
 175 unw_set_reg()
 176 writes an integer register, and
 177 unw_set_fpreg()
 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
 182 \fIcallee\-saved\fP
 183 (``preserved\&'') registers. However, in some
 184 special circumstances (e.g., in a signal handler trampoline), even the
 185 \fIcaller\-saved\fP
 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
 196 and UNW_REG_SP,
 197 respectively.
 198 .PP
 199 Besides just moving the unwind cursor and reading/writing saved
 200 registers, libunwind
 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
 206 unw_resume()
 207 and passing the cursor identifying the target
 208 frame as the only argument.
 209 .PP
 210 Normally, libunwind
 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
 217 UNW_LOCAL_ONLY
 218 before including the headerfile
 219 <libunwind.h>\&.
 220 It is perfectly OK for a single program to
 221 employ both local\-only and generic unwinding. That is, whether or not
 222 UNW_LOCAL_ONLY
 223 is defined is a choice that each source\-file
 224 (compilation\-unit) can make on its own. Independent of the setting(s)
 225 of UNW_LOCAL_ONLY,
 226 you\&'ll always link the same library into
 227 the program (normally \fB\-l\fPunwind).
 228 Furthermore, the
 229 portion of libunwind
 230 that manages unwind\-info for dynamically
 231 generated code is not affected by the setting of
 232 UNW_LOCAL_ONLY\&.
 233 .PP
 234 If we put all of the above together, here is how we could use
 235 libunwind
 236 to write a function ``show_backtrace()\&''
 237 which prints a classic stack trace:
 238 .PP
 239 .Vb
 240 #define UNW_LOCAL_ONLY
 241 #include <libunwind.h>
 242
 243 void show_backtrace (void) {
 244   unw_cursor_t cursor; unw_context_t uc;
 245   unw_word_t ip, sp;
 246
 247   unw_getcontext(&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);
 253   }
 254 }
 255 .Ve
 256 .PP
 257 .SH REMOTE UNWINDING
 258
 259 .PP
 260 Libunwind
 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.
 267 .PP
 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
 273 routines and an
 274 integer that specifies the byte\-order of the target process. The
 275 accessor routines provide libunwind
 276 with the means to
 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\&.
 280 .PP
 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
 284 unw_init_local(),
 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
 288 never
 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.
 292 .PP
 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
 295 unw_step()
 296 to move ``up\&'' in the call\-chain, read and write
 297 registers, or resume execution at a particular stack frame by calling
 298 unw_resume\&.
 299 .PP
 300 .SH CROSS\-PLATFORM AND MULTI\-PLATFORM UNWINDING
 301
 302 .PP
 303 Libunwind
 304 has been designed to enable unwinding across
 305 platforms (architectures). Indeed, a single program can use
 306 libunwind
 307 to unwind an arbitrary number of target platforms,
 308 all at the same time!
 309 .PP
 310 We call the machine that is running libunwind
 311 the \fIhost\fP
 312 and the machine that is running the process being unwound the
 313 \fItarget\fP\&.
 314 If the host and the target platform are the same, we
 315 call it \fInative\fP
 316 unwinding. If they differ, we call it
 317 \fIcross\-platform\fP
 318 unwinding.
 319 .PP
 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
 324 \fB\-l\fPunwind\&.
 325 For cross\-platform unwinding, a program
 326 includes <libunwind\-PLAT\&.h>
 327 and uses the linker
 328 switch \fB\-l\fPunwind\-PLAT,
 329 where PLAT
 330 is the name
 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
 341 issue in practice.
 342 .PP
 343 Note that, by definition, local unwinding is possible only for the
 344 native case. Attempting to call, e.g., unw_local_init()
 345 when
 346 targeting a cross\-platform will result in a link\-time error
 347 (unresolved references).
 348 .PP
 349 .SH THREAD\- AND SIGNAL\-SAFETY
 350
 351 .PP
 352 All libunwind
 353 routines are thread\-safe. What this means is
 354 that multiple threads may use libunwind
 355 simulatenously.
 356 However, any given cursor may be accessed by only one thread at
 357 any given time.
 358 .PP
 359 To ensure thread\-safety, some libunwind
 360 routines may have to
 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
 365 routine
 366 identifies whether or not it is signal\-safe, but as a general rule,
 367 any routine that may be needed for \fIlocal\fP
 368 unwinding is
 369 signal\-safe (e.g., unw_step()
 370 for local unwinding is
 371 signal\-safe). For remote\-unwinding, \fInone\fP
 372 of the
 373 libunwind
 374 routines are guaranteed to be signal\-safe.
 375 .PP
 376 .SH UNWINDING THROUGH DYNAMICALLY GENERATED CODE
 377
 378 .PP
 379 Libunwind
 380 provides the routines _U_dyn_register()
 381 and
 382 _U_dyn_cancel()
 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.
 390 .PP
 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.
 398 .PP
 399 For more information on the libunwind
 400 support for dynamically
 401 generated code, see libunwind\-dynamic(3)\&.
 402 .PP
 403 .SH CACHING OF UNWIND INFO
 404
 405 .PP
 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
 410 using
 411 stale data. For example, this would happen if libunwind
 412 were
 413 to cache information about a shared library which later on gets
 414 unloaded (e.g., via \fIdlclose\fP(3)).
 415 .PP
 416 To prevent the risk of using stale data, libunwind
 417 provides two
 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
 421 unw_flush_cache().
 422 The second facility is provided by
 423 unw_set_caching_policy(),
 424 which lets a program
 425 select the exact caching policy in use for a given address\-space
 426 object. In particular, by selecting the policy
 427 UNW_CACHE_NONE,
 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.
 432 .PP
 433 .SH FILES
 434
 435 .PP
 436 .TP
 437 libunwind.h
 438  Headerfile to include for native (same
 439 platform) unwinding.
 440 .TP
 441 libunwind\-PLAT\&.h
 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
 446 should be
 447 included.
 448 .TP
 449 \fB\-l\fPunwind
 450  Linker\-switch to add when building a
 451 program that does native (same platform) unwinding.
 452 .TP
 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
 457 \-lunwind\-ia64
 458 should be added. Note: multiple such switches
 459 may need to be specified for programs that can unwind programs on
 460 multiple platforms.
 461 .PP
 462 .SH SEE ALSO
 463
 464 .PP
 465 libunwind\-dynamic(3),
 466 libunwind\-ia64(3),
 467 libunwind\-ptrace(3),
 468 libunwind\-setjmp(3),
 469 unw_create_addr_space(3),
 470 unw_destroy_addr_space(3),
 471 unw_flush_cache(3),
 472 unw_get_accessors(3),
 473 unw_get_fpreg(3),
 474 unw_get_proc_info(3),
 475 unw_get_proc_name(3),
 476 unw_get_reg(3),
 477 unw_getcontext(3),
 478 unw_init_local(3),
 479 unw_init_remote(3),
 480 unw_is_fpreg(3),
 481 unw_is_signal_frame(3),
 482 unw_regname(3),
 483 unw_resume(3),
 484 unw_set_caching_policy(3),
 485 unw_set_fpreg(3),
 486 unw_set_reg(3),
 487 unw_step(3),
 488 unw_strerror(3),
 489 _U_dyn_register(3),
 490 _U_dyn_cancel(3)
 491 .PP
 492 .SH AUTHOR
 493
 494 .PP
 495 David Mosberger\-Tang
 496 .br
 497 Email: \fBdmosberger@gmail.com\fP
 498 .br
 499 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 500 .\" NOTE: This file is generated, DO NOT EDIT.