Provided by: libunwind8-dev_1.1-2.2ubuntu3_amd64 bug

NAME

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

SYNOPSIS

       #include <libunwind.h>

       int unw_getcontext(unw_context_t *);
       int unw_init_local(unw_cursor_t *, unw_context_t *);
       int unw_init_remote(unw_cursor_t *, unw_addr_space_t, void *);
       int unw_step(unw_cursor_t *);
       int unw_get_reg(unw_cursor_t *, unw_regnum_t, unw_word_t *);
       int unw_get_fpreg(unw_cursor_t *, unw_regnum_t, unw_fpreg_t *);
       int unw_set_reg(unw_cursor_t *, unw_regnum_t, unw_word_t);
       int unw_set_fpreg(unw_cursor_t *, unw_regnum_t, unw_fpreg_t);
       int unw_resume(unw_cursor_t *);

       unw_addr_space_t unw_local_addr_space;
       unw_addr_space_t unw_create_addr_space(unw_accessors_t, int);
       void unw_destroy_addr_space(unw_addr_space_t);
       unw_accessors_t unw_get_accessors(unw_addr_space_t);
       void unw_flush_cache(unw_addr_space_t, unw_word_t, unw_word_t);
       int unw_set_caching_policy(unw_addr_space_t, unw_caching_policy_t);

       const char *unw_regname(unw_regnum_t);
       int unw_get_proc_info(unw_cursor_t *, unw_proc_info_t *);
       int unw_get_save_loc(unw_cursor_t *, int, unw_save_loc_t *);
       int unw_is_fpreg(unw_regnum_t);
       int unw_is_signal_frame(unw_cursor_t *);
       int unw_get_proc_name(unw_cursor_t *, char *, size_t, unw_word_t *);

       void _U_dyn_register(unw_dyn_info_t *);
       void _U_dyn_cancel(unw_dyn_info_t *);

LOCAL UNWINDING

       Libunwind  is  very easy to use when unwinding a stack from within a running program. This
       is called local unwinding. Say you want to  unwind  the  stack  while  executing  in  some
       function  F().  In this function, you would call unw_getcontext() to get a snapshot of the
       CPU registers (machine-state).  Then  you  initialize  an  unwind  cursor  based  on  this
       snapshot.  This  is  done  with  a call to unw_init_local().  The cursor now points to the
       current frame, that is, the stack frame that corresponds  to  the  current  activation  of
       function  F().   The unwind cursor can then be moved ``up'' (towards earlier stack frames)
       by calling unw_step().  By repeatedly calling this routine, you  can  uncover  the  entire
       call-chain  that  led  to  the  activation  of function F().  A positive return value from
       unw_step() indicates that there are more frames in the chain, zero indicates that the  end
       of  the  chain  has been reached, and any negative value indicates that some sort of error
       has occurred.

       While it is not possible to directly move the unwind  cursor  in  the  ``down''  direction
       (towards  newer  stack  frames), this effect can be achieved by making copies of an unwind
       cursor. For example, a program that sometimes has to move  ``down''  by  one  stack  frame
       could  maintain  two cursor variables: ``curr'' and ``prev''.  The former would be used as
       the current cursor and prev would be  maintained  as  the  ``previous  frame''  cursor  by
       copying the contents of curr to prev right before calling unw_step().  With this approach,
       the program could move one step ``down'' simply by copying back prev to curr whenever that
       is  necessary.  In  the  most extreme case, a program could maintain a separate cursor for
       each call frame and that way it could move up and down the callframe-chain at will.

       Given an unwind cursor, it is possible to read and  write  the  CPU  registers  that  were
       preserved  for  the  current stack frame (as identified by the cursor). Libunwind provides
       several routines for this purpose: unw_get_reg()  reads  an  integer  (general)  register,
       unw_get_fpreg() reads a floating-point register, unw_set_reg() writes an integer register,
       and unw_set_fpreg() writes a floating-point register. Note that, by definition,  only  the
       preserved  machine  state can be accessed during an unwind operation. Normally, this state
       consists  of  the  callee-saved  (``preserved'')  registers.  However,  in  some   special
       circumstances  (e.g., in a signal handler trampoline), even the caller-saved (``scratch'')
       registers are preserved in the stack frame and,  in  those  cases,  libunwind  will  grant
       access  to  them  as  well. The exact set of registers that can be accessed via the cursor
       depends, of course, on the platform. However, there are two registers that can be read  on
       all  platforms:  the  instruction  pointer  (IP),  sometimes  also  known as the ``program
       counter'', and the stack pointer (SP). In libunwind, these registers are identified by the
       macros UNW_REG_IP and UNW_REG_SP, respectively.

       Besides  just moving the unwind cursor and reading/writing saved registers, libunwind also
       provides the ability to resume execution at an arbitrary stack frame. As you might  guess,
       this  is useful for implementing non-local gotos and the exception handling needed by some
       high-level languages such as Java. Resuming execution with a particular stack frame simply
       requires  calling  unw_resume() and passing the cursor identifying the target frame as the
       only argument.

       Normally, libunwind supports both local and remote unwinding (the latter will be explained
       in  the  next  section). However, if you tell libunwind that your program only needs local
       unwinding, then a special implementation can be selected which may run  much  faster  than
       the  generic  implementation  which  supports  both  kinds  of  unwinding.  To select this
       optimized version, simply define the macro UNW_LOCAL_ONLY before including the  headerfile
       <libunwind.h>.   It  is  perfectly  OK  for a single program to employ both local-only and
       generic unwinding. That is, whether or not UNW_LOCAL_ONLY is defined is a choice that each
       source-file  (compilation-unit)  can  make  on  its  own. Independent of the setting(s) of
       UNW_LOCAL_ONLY, you'll always link the same library into the program (normally  -lunwind).
       Furthermore,  the  portion of libunwind that manages unwind-info for dynamically generated
       code is not affected by the setting of UNW_LOCAL_ONLY.

       If we put all of the above together, here is  how  we  could  use  libunwind  to  write  a
       function ``show_backtrace()'' which prints a classic stack trace:

       #define UNW_LOCAL_ONLY
       #include <libunwind.h>

       void show_backtrace (void) {
         unw_cursor_t cursor; unw_context_t uc;
         unw_word_t ip, sp;

         unw_getcontext(&uc);
         unw_init_local(&cursor, &uc);
         while (unw_step(&cursor) > 0) {
           unw_get_reg(&cursor, UNW_REG_IP, &ip);
           unw_get_reg(&cursor, UNW_REG_SP, &sp);
           printf ("ip = %lx, sp = %lx\n", (long) ip, (long) sp);
         }
       }

REMOTE UNWINDING

       Libunwind can also be used to unwind a stack in a ``remote'' process. Here, ``remote'' may
       mean another process on the same machine or even  a  process  on  a  completely  different
       machine  from  the  one  that is running libunwind.  Remote unwinding is typically used by
       debuggers and instruction-set simulators, for example.

       Before you can unwind a remote process, you need to create a new address-space object  for
       that process. This is achieved with the unw_create_addr_space() routine. The routine takes
       two arguments: a pointer to a set of accessor routines and an integer that  specifies  the
       byte-order  of  the target process. The accessor routines provide libunwind with the means
       to communicate with the remote process. In particular, there are  callbacks  to  read  and
       write  the  process's memory, its registers, and to access unwind information which may be
       needed by libunwind.

       With the address space created, unwinding can be initiated by a call to unw_init_remote().
       This  routine  is  very similar to unw_init_local(), except that it takes an address-space
       object and an opaque pointer as arguments. The routine uses these arguments to  fetch  the
       initial  machine  state.  Libunwind  never uses the opaque pointer on its own, but instead
       just passes it on to the accessor (callback) routines. Typically, this pointer is used  to
       select, e.g., the thread within a process that is to be unwound.

       Once a cursor has been initialized with unw_init_remote(), unwinding works exactly like in
       the local case. That is, you can use unw_step() to move ``up'' in the call-chain, read and
       write registers, or resume execution at a particular stack frame by calling unw_resume.

CROSS-PLATFORM AND MULTI-PLATFORM UNWINDING

       Libunwind  has been designed to enable unwinding across platforms (architectures). Indeed,
       a single program can use libunwind to unwind an arbitrary number of target platforms,  all
       at the same time!

       We call the machine that is running libunwind the host and the machine that is running the
       process being unwound the target.  If the host and the target platform are  the  same,  we
       call it native unwinding. If they differ, we call it cross-platform unwinding.

       The  principle  behind  supporting native, cross-platform, and multi-platform unwinding is
       very simple: for native unwinding, a program includes <libunwind.h> and  uses  the  linker
       switch  -lunwind.  For cross-platform unwinding, a program includes <libunwind-PLAT.h> and
       uses the linker switch -lunwind-PLAT, where PLAT is the name of the target platform (e.g.,
       ia64  for  IA-64,  hppa-elf  for  ELF-based  HP PA-RISC, or x86 for 80386). Multi-platform
       unwinding works exactly like cross-platform unwinding,  the  only  limitation  is  that  a
       single  source  file  (compilation unit) can include at most one libunwind header file. In
       other words, the platform-specific support for each supported target needs to be  isolated
       in separate source files---a limitation that shouldn't be an issue in practice.

       Note that, by definition, local unwinding is possible only for the native case. Attempting
       to call, e.g., unw_local_init() when targeting a cross-platform will result in a link-time
       error (unresolved references).

THREAD- AND SIGNAL-SAFETY

       All  libunwind  routines are thread-safe. What this means is that multiple threads may use
       libunwind simulatenously.  However, any given cursor may be accessed by only one thread at
       any given time.

       To  ensure  thread-safety,  some libunwind routines may have to use locking. Such routines
       must not be called from signal handlers (directly or indirectly)  and  are  therefore  not
       signal-safe.  The  manual  page for each libunwind routine identifies whether or not it is
       signal-safe, but as a general rule, any routine that may be needed for local unwinding  is
       signal-safe  (e.g.,  unw_step() for local unwinding is signal-safe). For remote-unwinding,
       none of the libunwind routines are guaranteed to be signal-safe.

UNWINDING THROUGH DYNAMICALLY GENERATED CODE

       Libunwind provides the routines _U_dyn_register() and _U_dyn_cancel()  to  register/cancel
       the  information required to unwind through code that has been generated at runtime (e.g.,
       by a just-in-time (JIT) compiler). It is important to register  the  information  for  all
       dynamically  generated  code  because  otherwise,  a  debugger may not be able to function
       properly or high-level language exception handling may not work as expected.

       The interface for registering and canceling dynamic unwind  info  has  been  designed  for
       maximum  efficiency,  so  as  to  minimize  the  performance  impact  on JIT-compilers. In
       particular, both routines are guaranteed to execute in ``constant time''  (O(1))  and  the
       data-structure  encapsulating  the  dynamic  unwind  info  has been designed to facilitate
       sharing, such that similar procedures can share much of the underlying information.

       For more information  on  the  libunwind  support  for  dynamically  generated  code,  see
       libunwind-dynamic(3).

CACHING OF UNWIND INFO

       To  speed  up  execution,  libunwind  may  aggressively  cache the information it needs to
       perform unwinding. If a process changes during  its  lifetime,  this  creates  a  risk  of
       libunwind  using  stale  data.  For  example, this would happen if libunwind were to cache
       information about a shared library which later on gets unloaded (e.g., via dlclose(3)).

       To prevent the risk of using stale data, libunwind provides two facilities: first,  it  is
       possible  to  flush the cached information associated with a specific address range in the
       target process (or the entire address space, if desired). This functionality  is  provided
       by  unw_flush_cache().  The second facility is provided by unw_set_caching_policy(), which
       lets a program select the exact caching policy in use for a given address-space object. In
       particular,  by  selecting  the  policy UNW_CACHE_NONE, it is possible to turn off caching
       completely, therefore eliminating the risk of stale  data  alltogether  (at  the  cost  of
       slower execution). By default, caching is enabled for local unwinding only.

FILES

       libunwind.h
               Headerfile to include for native (same platform) unwinding.

       libunwind-PLAT.h
               Headerfile  to include when the unwind target runs on platform PLAT.  For example,
              to unwind an IA-64 program, the header file libunwind-ia64.h should be included.

       -lunwind
               Linker-switch to add when building a program  that  does  native  (same  platform)
              unwinding.

       -lunwind-PLAT
               Linker-switch  to  add  when building a program that unwinds a program on platform
              PLAT.   For  example,  to  (cross-)unwind  an  IA-64  program,  the  linker  switch
              -lunwind-ia64  should  be  added.  Note:  multiple  such  switches  may  need to be
              specified for programs that can unwind programs on multiple platforms.

SEE ALSO

       libunwind-dynamic(3),   libunwind-ia64(3),    libunwind-ptrace(3),    libunwind-setjmp(3),
       unw_create_addr_space(3),          unw_destroy_addr_space(3),          unw_flush_cache(3),
       unw_get_accessors(3),   unw_get_fpreg(3),   unw_get_proc_info(3),    unw_get_proc_name(3),
       unw_get_reg(3), unw_getcontext(3), unw_init_local(3), unw_init_remote(3), unw_is_fpreg(3),
       unw_is_signal_frame(3),    unw_regname(3),    unw_resume(3),    unw_set_caching_policy(3),
       unw_set_fpreg(3),   unw_set_reg(3),   unw_step(3),   unw_strerror(3),  _U_dyn_register(3),
       _U_dyn_cancel(3)

AUTHOR

       David Mosberger-Tang
       Email: dmosberger@gmail.com
       WWW: http://www.nongnu.org/libunwind/.