doc/libunwind.man

   1 '\" t
   2 .\" Manual page created with latex2man on Thu Jan 12 06:50:29 PST 2017
   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" "12 January 2017" "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 int
  86 unw_set_cache_size(unw_addr_space_t,
  87 size_t,
  88 int);
  89 .br
  90 .PP
  91 const char *unw_regname(unw_regnum_t);
  92 .br
  93 int
  94 unw_get_proc_info(unw_cursor_t *,
  95 unw_proc_info_t *);
  96 .br
  97 int
  98 unw_get_save_loc(unw_cursor_t *,
  99 int,
 100 unw_save_loc_t *);
 101 .br
 102 int
 103 unw_is_fpreg(unw_regnum_t);
 104 .br
 105 int
 106 unw_is_signal_frame(unw_cursor_t *);
 107 .br
 108 int
 109 unw_get_proc_name(unw_cursor_t *,
 110 char *,
 111 size_t,
 112 unw_word_t *);
 113 .br
 114 .PP
 115 void
 116 _U_dyn_register(unw_dyn_info_t *);
 117 .br
 118 void
 119 _U_dyn_cancel(unw_dyn_info_t *);
 120 .br
 121 .PP
 122 .SH LOCAL UNWINDING
 123
 124 .PP
 125 Libunwind
 126 is very easy to use when unwinding a stack from
 127 within a running program. This is called \fIlocal\fP
 128 unwinding. Say
 129 you want to unwind the stack while executing in some function
 130 F().
 131 In this function, you would call unw_getcontext()
 132 to get a snapshot of the CPU registers (machine\-state). Then you
 133 initialize an \fIunwind cursor\fP
 134 based on this snapshot. This is
 135 done with a call to unw_init_local().
 136 The cursor now points
 137 to the current frame, that is, the stack frame that corresponds to the
 138 current activation of function F().
 139 The unwind cursor can then
 140 be moved ``up\&'' (towards earlier stack frames) by calling
 141 unw_step().
 142 By repeatedly calling this routine, you can
 143 uncover the entire call\-chain that led to the activation of function
 144 F().
 145 A positive return value from unw_step()
 146 indicates
 147 that there are more frames in the chain, zero indicates that the end
 148 of the chain has been reached, and any negative value indicates that
 149 some sort of error has occurred.
 150 .PP
 151 While it is not possible to directly move the unwind cursor in the
 152 ``down\&'' direction (towards newer stack frames), this effect can be
 153 achieved by making copies of an unwind cursor. For example, a program
 154 that sometimes has to move ``down\&'' by one stack frame could maintain
 155 two cursor variables: ``curr\&''
 156 and ``prev\&''\&.
 157 The former
 158 would be used as the current cursor and prev
 159 would be maintained
 160 as the ``previous frame\&'' cursor by copying the contents of curr
 161 to prev
 162 right before calling unw_step().
 163 With this
 164 approach, the program could move one step ``down\&'' simply by copying
 165 back prev
 166 to curr
 167 whenever that is necessary. In the most
 168 extreme case, a program could maintain a separate cursor for each call
 169 frame and that way it could move up and down the callframe\-chain at
 170 will.
 171 .PP
 172 Given an unwind cursor, it is possible to read and write the CPU
 173 registers that were preserved for the current stack frame (as
 174 identified by the cursor). Libunwind
 175 provides several routines
 176 for this purpose: unw_get_reg()
 177 reads an integer (general)
 178 register, unw_get_fpreg()
 179 reads a floating\-point register,
 180 unw_set_reg()
 181 writes an integer register, and
 182 unw_set_fpreg()
 183 writes a floating\-point register. Note that,
 184 by definition, only the \fIpreserved\fP
 185 machine state can be accessed
 186 during an unwind operation. Normally, this state consists of the
 187 \fIcallee\-saved\fP
 188 (``preserved\&'') registers. However, in some
 189 special circumstances (e.g., in a signal handler trampoline), even the
 190 \fIcaller\-saved\fP
 191 (``scratch\&'') registers are preserved in the stack
 192 frame and, in those cases, libunwind
 193 will grant access to them
 194 as well. The exact set of registers that can be accessed via the
 195 cursor depends, of course, on the platform. However, there are two
 196 registers that can be read on all platforms: the instruction pointer
 197 (IP), sometimes also known as the ``program counter\&'', and the stack
 198 pointer (SP). In libunwind,
 199 these registers are identified by
 200 the macros UNW_REG_IP
 201 and UNW_REG_SP,
 202 respectively.
 203 .PP
 204 Besides just moving the unwind cursor and reading/writing saved
 205 registers, libunwind
 206 also provides the ability to resume
 207 execution at an arbitrary stack frame. As you might guess, this is
 208 useful for implementing non\-local gotos and the exception handling
 209 needed by some high\-level languages such as Java. Resuming execution
 210 with a particular stack frame simply requires calling
 211 unw_resume()
 212 and passing the cursor identifying the target
 213 frame as the only argument.
 214 .PP
 215 Normally, libunwind
 216 supports both local and remote unwinding
 217 (the latter will be explained in the next section). However, if you
 218 tell libunwind that your program only needs local unwinding, then a
 219 special implementation can be selected which may run much faster than
 220 the generic implementation which supports both kinds of unwinding. To
 221 select this optimized version, simply define the macro
 222 UNW_LOCAL_ONLY
 223 before including the headerfile
 224 <libunwind.h>\&.
 225 It is perfectly OK for a single program to
 226 employ both local\-only and generic unwinding. That is, whether or not
 227 UNW_LOCAL_ONLY
 228 is defined is a choice that each source\-file
 229 (compilation\-unit) can make on its own. Independent of the setting(s)
 230 of UNW_LOCAL_ONLY,
 231 you\&'ll always link the same library into
 232 the program (normally \fB\-l\fPunwind).
 233 Furthermore, the
 234 portion of libunwind
 235 that manages unwind\-info for dynamically
 236 generated code is not affected by the setting of
 237 UNW_LOCAL_ONLY\&.
 238 .PP
 239 If we put all of the above together, here is how we could use
 240 libunwind
 241 to write a function ``show_backtrace()\&''
 242 which prints a classic stack trace:
 243 .PP
 244 .Vb
 245 #define UNW_LOCAL_ONLY
 246 #include <libunwind.h>
 247
 248 void show_backtrace (void) {
 249   unw_cursor_t cursor; unw_context_t uc;
 250   unw_word_t ip, sp;
 251
 252   unw_getcontext(&uc);
 253   unw_init_local(&cursor, &uc);
 254   while (unw_step(&cursor) > 0) {
 255     unw_get_reg(&cursor, UNW_REG_IP, &ip);
 256     unw_get_reg(&cursor, UNW_REG_SP, &sp);
 257     printf ("ip = %lx, sp = %lx\\n", (long) ip, (long) sp);
 258   }
 259 }
 260 .Ve
 261 .PP
 262 .SH REMOTE UNWINDING
 263
 264 .PP
 265 Libunwind
 266 can also be used to unwind a stack in a ``remote\&''
 267 process. Here, ``remote\&'' may mean another process on the same
 268 machine or even a process on a completely different machine from the
 269 one that is running libunwind\&.
 270 Remote unwinding is typically
 271 used by debuggers and instruction\-set simulators, for example.
 272 .PP
 273 Before you can unwind a remote process, you need to create a new
 274 address\-space object for that process. This is achieved with the
 275 unw_create_addr_space()
 276 routine. The routine takes two
 277 arguments: a pointer to a set of \fIaccessor\fP
 278 routines and an
 279 integer that specifies the byte\-order of the target process. The
 280 accessor routines provide libunwind
 281 with the means to
 282 communicate with the remote process. In particular, there are
 283 callbacks to read and write the process\&'s memory, its registers, and
 284 to access unwind information which may be needed by libunwind\&.
 285 .PP
 286 With the address space created, unwinding can be initiated by a call
 287 to unw_init_remote().
 288 This routine is very similar to
 289 unw_init_local(),
 290 except that it takes an address\-space
 291 object and an opaque pointer as arguments. The routine uses these
 292 arguments to fetch the initial machine state. Libunwind
 293 never
 294 uses the opaque pointer on its own, but instead just passes it on to
 295 the accessor (callback) routines. Typically, this pointer is used to
 296 select, e.g., the thread within a process that is to be unwound.
 297 .PP
 298 Once a cursor has been initialized with unw_init_remote(),
 299 unwinding works exactly like in the local case. That is, you can use
 300 unw_step()
 301 to move ``up\&'' in the call\-chain, read and write
 302 registers, or resume execution at a particular stack frame by calling
 303 unw_resume\&.
 304 .PP
 305 .SH CROSS\-PLATFORM AND MULTI\-PLATFORM UNWINDING
 306
 307 .PP
 308 Libunwind
 309 has been designed to enable unwinding across
 310 platforms (architectures). Indeed, a single program can use
 311 libunwind
 312 to unwind an arbitrary number of target platforms,
 313 all at the same time!
 314 .PP
 315 We call the machine that is running libunwind
 316 the \fIhost\fP
 317 and the machine that is running the process being unwound the
 318 \fItarget\fP\&.
 319 If the host and the target platform are the same, we
 320 call it \fInative\fP
 321 unwinding. If they differ, we call it
 322 \fIcross\-platform\fP
 323 unwinding.
 324 .PP
 325 The principle behind supporting native, cross\-platform, and
 326 multi\-platform unwinding is very simple: for native unwinding, a
 327 program includes <libunwind.h>
 328 and uses the linker switch
 329 \fB\-l\fPunwind\&.
 330 For cross\-platform unwinding, a program
 331 includes <libunwind\-PLAT\&.h>
 332 and uses the linker
 333 switch \fB\-l\fPunwind\-PLAT,
 334 where PLAT
 335 is the name
 336 of the target platform (e.g., ia64
 337 for IA\-64, hppa\-elf
 338 for ELF\-based HP PA\-RISC, or x86
 339 for 80386). Multi\-platform
 340 unwinding works exactly like cross\-platform unwinding, the only
 341 limitation is that a single source file (compilation unit) can include
 342 at most one libunwind
 343 header file. In other words, the
 344 platform\-specific support for each supported target needs to be
 345 isolated in separate source files\-\-\-a limitation that shouldn\&'t be an
 346 issue in practice.
 347 .PP
 348 Note that, by definition, local unwinding is possible only for the
 349 native case. Attempting to call, e.g., unw_local_init()
 350 when
 351 targeting a cross\-platform will result in a link\-time error
 352 (unresolved references).
 353 .PP
 354 .SH THREAD\- AND SIGNAL\-SAFETY
 355
 356 .PP
 357 All libunwind
 358 routines are thread\-safe. What this means is
 359 that multiple threads may use libunwind
 360 simulatenously.
 361 However, any given cursor may be accessed by only one thread at
 362 any given time.
 363 .PP
 364 To ensure thread\-safety, some libunwind
 365 routines may have to
 366 use locking. Such routines \fImust not\fP
 367 be called from signal
 368 handlers (directly or indirectly) and are therefore \fInot\fP
 369 signal\-safe. The manual page for each libunwind
 370 routine
 371 identifies whether or not it is signal\-safe, but as a general rule,
 372 any routine that may be needed for \fIlocal\fP
 373 unwinding is
 374 signal\-safe (e.g., unw_step()
 375 for local unwinding is
 376 signal\-safe). For remote\-unwinding, \fInone\fP
 377 of the
 378 libunwind
 379 routines are guaranteed to be signal\-safe.
 380 .PP
 381 .SH UNWINDING THROUGH DYNAMICALLY GENERATED CODE
 382
 383 .PP
 384 Libunwind
 385 provides the routines _U_dyn_register()
 386 and
 387 _U_dyn_cancel()
 388 to register/cancel the information required to
 389 unwind through code that has been generated at runtime (e.g., by a
 390 just\-in\-time (JIT) compiler). It is important to register the
 391 information for \fIall\fP
 392 dynamically generated code because
 393 otherwise, a debugger may not be able to function properly or
 394 high\-level language exception handling may not work as expected.
 395 .PP
 396 The interface for registering and canceling dynamic unwind info has
 397 been designed for maximum efficiency, so as to minimize the
 398 performance impact on JIT\-compilers. In particular, both routines are
 399 guaranteed to execute in ``constant time\&'' (O(1)) and the
 400 data\-structure encapsulating the dynamic unwind info has been designed
 401 to facilitate sharing, such that similar procedures can share much of
 402 the underlying information.
 403 .PP
 404 For more information on the libunwind
 405 support for dynamically
 406 generated code, see libunwind\-dynamic(3)\&.
 407 .PP
 408 .SH CACHING OF UNWIND INFO
 409
 410 .PP
 411 To speed up execution, libunwind
 412 may aggressively cache the
 413 information it needs to perform unwinding. If a process changes
 414 during its lifetime, this creates a risk of libunwind
 415 using
 416 stale data. For example, this would happen if libunwind
 417 were
 418 to cache information about a shared library which later on gets
 419 unloaded (e.g., via \fIdlclose\fP(3)).
 420 .PP
 421 To prevent the risk of using stale data, libunwind
 422 provides two
 423 facilities: first, it is possible to flush the cached information
 424 associated with a specific address range in the target process (or the
 425 entire address space, if desired). This functionality is provided by
 426 unw_flush_cache().
 427 The second facility is provided by
 428 unw_set_caching_policy(),
 429 which lets a program
 430 select the exact caching policy in use for a given address\-space
 431 object. In particular, by selecting the policy
 432 UNW_CACHE_NONE,
 433 it is possible to turn off caching
 434 completely, therefore eliminating the risk of stale data alltogether
 435 (at the cost of slower execution). By default, caching is enabled for
 436 local unwinding only. The cache size can be dynamically changed with
 437 unw_set_cache_size(),
 438 which also fluches the current cache.
 439 .PP
 440 .SH FILES
 441
 442 .PP
 443 .TP
 444 libunwind.h
 445  Headerfile to include for native (same
 446 platform) unwinding.
 447 .TP
 448 libunwind\-PLAT\&.h
 449  Headerfile to include when
 450 the unwind target runs on platform PLAT\&.
 451 For example, to unwind
 452 an IA\-64 program, the header file libunwind\-ia64.h
 453 should be
 454 included.
 455 .TP
 456 \fB\-l\fPunwind
 457  Linker\-switch to add when building a
 458 program that does native (same platform) unwinding.
 459 .TP
 460 \fB\-l\fPunwind\-PLAT
 461  Linker\-switch to add when
 462 building a program that unwinds a program on platform PLAT\&.
 463 For example, to (cross\-)unwind an IA\-64 program, the linker switch
 464 \-lunwind\-ia64
 465 should be added. Note: multiple such switches
 466 may need to be specified for programs that can unwind programs on
 467 multiple platforms.
 468 .PP
 469 .SH SEE ALSO
 470
 471 .PP
 472 libunwind\-dynamic(3),
 473 libunwind\-ia64(3),
 474 libunwind\-ptrace(3),
 475 libunwind\-setjmp(3),
 476 unw_create_addr_space(3),
 477 unw_destroy_addr_space(3),
 478 unw_flush_cache(3),
 479 unw_get_accessors(3),
 480 unw_get_fpreg(3),
 481 unw_get_proc_info(3),
 482 unw_get_proc_name(3),
 483 unw_get_reg(3),
 484 unw_getcontext(3),
 485 unw_init_local(3),
 486 unw_init_remote(3),
 487 unw_is_fpreg(3),
 488 unw_is_signal_frame(3),
 489 unw_regname(3),
 490 unw_resume(3),
 491 unw_set_caching_policy(3),
 492 unw_set_cache_size(3),
 493 unw_set_fpreg(3),
 494 unw_set_reg(3),
 495 unw_step(3),
 496 unw_strerror(3),
 497 _U_dyn_register(3),
 498 _U_dyn_cancel(3)
 499 .PP
 500 .SH AUTHOR
 501
 502 .PP
 503 David Mosberger\-Tang
 504 .br
 505 Email: \fBdmosberger@gmail.com\fP
 506 .br
 507 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 508 .\" NOTE: This file is generated, DO NOT EDIT.