xenial (3) libunwind.3.gz

Provided by: libunwind-dev_1.1-4.1_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/.