<NME> libunwind.tex
<BEF> \documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}

\input{common.tex}

\begin{document}

\begin{Name}{3}{libunwind}{David Mosberger-Tang}{Programming Library}{Introduction to libunwind}libunwind -- a (mostly) platform-independent unwind API
\end{Name}

\section{Synopsis}

\File{\#include $<$libunwind.h$>$}\\

\noindent
\Type{int} \Func{unw\_getcontext}(\Type{unw\_context\_t~*});\\
\noindent
\Type{int} \Func{unw\_init\_local}(\Type{unw\_cursor\_t~*}, \Type{unw\_context\_t~*});\\
\noindent
\Type{int} \Func{unw\_init\_remote}(\Type{unw\_cursor\_t~*}, \Type{unw\_addr\_space\_t}, \Type{void~*});\\
\noindent
\Type{int} \Func{unw\_step}(\Type{unw\_cursor\_t~*});\\
\noindent
\Type{int} \Func{unw\_get\_reg}(\Type{unw\_cursor\_t~*}, \Type{unw\_regnum\_t}, \Type{unw\_word\_t~*});\\
\noindent
\Type{int} \Func{unw\_get\_fpreg}(\Type{unw\_cursor\_t~*}, \Type{unw\_regnum\_t}, \Type{unw\_fpreg\_t~*});\\
\noindent
\Type{int} \Func{unw\_set\_reg}(\Type{unw\_cursor\_t~*}, \Type{unw\_regnum\_t}, \Type{unw\_word\_t});\\
\noindent
\Type{int} \Func{unw\_set\_fpreg}(\Type{unw\_cursor\_t~*}, \Type{unw\_regnum\_t}, \Type{unw\_fpreg\_t});\\
\noindent
\Type{int} \Func{unw\_resume}(\Type{unw\_cursor\_t~*});\\

\noindent
\Type{unw\_addr\_space\_t} \Var{unw\_local\_addr\_space};\\
\noindent
\Type{unw\_addr\_space\_t} \Func{unw\_create\_addr\_space}(\Type{unw\_accessors\_t}, \Type{int});\\
\noindent
\Type{void} \Func{unw\_destroy\_addr\_space}(\Type{unw\_addr\_space\_t});\\
\noindent
\Type{unw\_accessors\_t} \Func{unw\_get\_accessors}(\Type{unw\_addr\_space\_t});\\
\noindent
\Type{void} \Func{unw\_flush\_cache}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{unw\_word\_t});\\
\noindent
\Type{int} \Func{unw\_set\_caching\_policy}(\Type{unw\_addr\_space\_t}, \Type{unw\_caching\_policy\_t});\\
\noindent
\Type{int} \Func{unw\_set\_cache\_size}(\Type{unw\_addr\_space\_t}, \Type{size\_t}, \Type{int});\\

\noindent
\Type{const char *}\Func{unw\_regname}(\Type{unw\_regnum\_t});\\
\noindent
\Type{int} \Func{unw\_get\_proc\_info}(\Type{unw\_cursor\_t~*}, \Type{unw\_proc\_info\_t~*});\\
\noindent
\Type{int} \Func{unw\_get\_save\_loc}(\Type{unw\_cursor\_t~*}, \Type{int}, \Type{unw\_save\_loc\_t~*});\\
\noindent
\Type{int} \Func{unw\_is\_fpreg}(\Type{unw\_regnum\_t});\\
\Type{int} \Func{unw\_is\_signal\_frame}(\Type{unw\_cursor\_t~*});\\
\noindent
\Type{int} \Func{unw\_get\_proc\_name}(\Type{unw\_cursor\_t~*}, \Type{char~*}, \Type{size\_t}, \Type{unw\_word\_t~*});\\

\noindent
\Type{void} \Func{\_U\_dyn\_register}(\Type{unw\_dyn\_info\_t~*});\\
\noindent
\Type{void} \Func{\_U\_dyn\_cancel}(\Type{unw\_dyn\_info\_t~*});\\

\section{Local Unwinding}

\Prog{Libunwind} is very easy to use when unwinding a stack from
within a running program.  This is called \emph{local} unwinding.  Say
you want to unwind the stack while executing in some function
\Func{F}().  In this function, you would call \Func{unw\_getcontext}()
to get a snapshot of the CPU registers (machine-state).  Then you
initialize an \emph{unwind~cursor} based on this snapshot.  This is
done with a call to \Func{unw\_init\_local}().  The cursor now points
to the current frame, that is, the stack frame that corresponds to the
current activation of function \Func{F}().  The unwind cursor can then
be moved ``up'' (towards earlier stack frames) by calling
\Func{unw\_step}().  By repeatedly calling this routine, you can
uncover the entire call-chain that led to the activation of function
\Func{F}().  A positive return value from \Func{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: ``\Var{curr}'' and ``\Var{prev}''.  The former
would be used as the current cursor and \Var{prev} would be maintained
as the ``previous frame'' cursor by copying the contents of \Var{curr}
to \Var{prev} right before calling \Func{unw\_step}().  With this
approach, the program could move one step ``down'' simply by copying
back \Var{prev} to \Var{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).  \Prog{Libunwind} provides several routines
for this purpose: \Func{unw\_get\_reg}() reads an integer (general)
register, \Func{unw\_get\_fpreg}() reads a floating-point register,
\Func{unw\_set\_reg}() writes an integer register, and
\Func{unw\_set\_fpreg}() writes a floating-point register.  Note that,
by definition, only the \emph{preserved} machine state can be accessed
during an unwind operation.  Normally, this state consists of the
\emph{callee-saved} (``preserved'') registers.  However, in some
special circumstances (e.g., in a signal handler trampoline), even the
\emph{caller-saved} (``scratch'') registers are preserved in the stack
frame and, in those cases, \Prog{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 \Prog{libunwind}, these registers are identified by
the macros \Const{UNW\_REG\_IP} and \Const{UNW\_REG\_SP},
respectively.

Besides just moving the unwind cursor and reading/writing saved
registers, \Prog{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
\Func{unw\_resume}() and passing the cursor identifying the target
frame as the only argument.

Normally, \Prog{libunwind} supports both local and remote unwinding
(the latter will be explained in the next section).  However, if you
tell \Prog{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
\Const{UNW\_LOCAL\_ONLY} before including the headerfile
\File{$<$libunwind.h$>$}.  It is perfectly OK for a single program to
employ both local-only and generic unwinding.  That is, whether or not
\Const{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 \Const{UNW\_LOCAL\_ONLY}, you'll always link the same library into
the program (normally \Opt{-l}\File{unwind}).  Furthermore, the
portion of \Prog{libunwind} that manages unwind-info for dynamically
generated code is not affected by the setting of
\Const{UNW\_LOCAL\_ONLY}.

If we put all of the above together, here is how we could use
\Prog{libunwind} to write a function ``\Func{show\_backtrace}()''
which prints a classic stack trace:

\begin{verbatim}
#define UNW_LOCAL_ONLY
#include <libunwind.h>

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

  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);
  }
}
\end{verbatim}
}
\end{verbatim}


\section{Remote Unwinding}

\Prog{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 \Prog{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
\Func{unw\_create\_addr\_space}() routine.  The routine takes two
arguments: a pointer to a set of \emph{accessor} routines and an
integer that specifies the byte-order of the target process.  The
accessor routines provide \Func{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 \Func{libunwind}.

With the address space created, unwinding can be initiated by a call
to \Func{unw\_init\_remote}().  This routine is very similar to
\Func{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.  \Prog{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 \Func{unw\_init\_remote}(),
unwinding works exactly like in the local case.  That is, you can use
\Func{unw\_step}() to move ``up'' in the call-chain, read and write
registers, or resume execution at a particular stack frame by calling
\Func{unw\_resume}.


\section{Cross-platform and Multi-platform Unwinding}

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

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

The principle behind supporting native, cross-platform, and
multi-platform unwinding is very simple: for native unwinding, a
program includes \File{$<$libunwind.h$>$} and uses the linker switch
\Opt{-l}\File{unwind}.  For cross-platform unwinding, a program
includes \File{$<$libunwind-}\Var{PLAT}\File{.h$>$} and uses the linker
switch \Opt{-l}\File{unwind-}\Var{PLAT}, where \Var{PLAT} is the name
of the target platform (e.g., \File{ia64} for IA-64, \File{hppa-elf}
for ELF-based HP PA-RISC, or \File{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 \Prog{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., \Func{unw\_local\_init}() when
targeting a cross-platform will result in a link-time error
(unresolved references).


\section{Thread- and Signal-Safety}


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

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


\section{Unwinding Through Dynamically Generated Code}

\Func{Libunwind} provides the routines \Func{\_U\_dyn\_register}() and
\Func{\_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 \emph{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 \Prog{libunwind} support for dynamically
generated code, see \SeeAlso{libunwind-dynamic(3)}.


\section{Caching of Unwind Info}

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

To prevent the risk of using stale data, \Prog{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
\Func{unw\_flush\_cache}().  The second facility is provided by
\Func{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
\Const{UNW\_CACHE\_NONE}, it is possible to turn off caching
completely, therefore eliminating the risk of stale data altogether
(at the cost of slower execution).  By default, caching is enabled for
local unwinding only.  The cache size can be dynamically changed with
\Func{unw\_set\_cache\_size}(), which also flushes the current cache.


\section{Files}

\begin{Description}
\item[\File{libunwind.h}] Headerfile to include for native (same
  platform) unwinding.
\item[\File{libunwind-}\Var{PLAT}\File{.h}] Headerfile to include when
  the unwind target runs on platform \Var{PLAT}.  For example, to unwind
  an IA-64 program, the header file \File{libunwind-ia64.h} should be
  included.
\item[\Opt{-l}\File{unwind}] Linker-switch to add when building a
  program that does native (same platform) unwinding.
\item[\Opt{-l}\File{unwind-}\Var{PLAT}] Linker-switch to add when
  building a program that unwinds a program on platform \Var{PLAT}.
  For example, to (cross-)unwind an IA-64 program, the linker switch
  \File{-lunwind-ia64} should be added.  Note: multiple such switches
  may need to be specified for programs that can unwind programs on
  multiple platforms.
\end{Description}

\section{See Also}

\SeeAlso{libunwind-dynamic(3)},
\SeeAlso{libunwind-ia64(3)},
\SeeAlso{libunwind-ptrace(3)},
\SeeAlso{libunwind-setjmp(3)},
\SeeAlso{unw\_create\_addr\_space(3)},
\SeeAlso{unw\_destroy\_addr\_space(3)},
\SeeAlso{unw\_flush\_cache(3)},
\SeeAlso{unw\_get\_accessors(3)},
\SeeAlso{unw\_get\_fpreg(3)},
\SeeAlso{unw\_get\_proc\_info(3)},
\SeeAlso{unw\_get\_proc\_name(3)},
\SeeAlso{unw\_get\_reg(3)},
\SeeAlso{unw\_getcontext(3)},
\SeeAlso{unw\_init\_local(3)},
\SeeAlso{unw\_init\_remote(3)},
\SeeAlso{unw\_is\_fpreg(3)},
\SeeAlso{unw\_is\_signal\_frame(3)},
\SeeAlso{unw\_regname(3)},
\SeeAlso{unw\_resume(3)},
\SeeAlso{unw\_set\_caching\_policy(3)},
\SeeAlso{unw\_set\_cache\_size(3)},
\SeeAlso{unw\_set\_fpreg(3)},
\SeeAlso{unw\_set\_reg(3)},
\SeeAlso{unw\_step(3)},
\SeeAlso{unw\_strerror(3)},
\SeeAlso{\_U\_dyn\_register(3)},
\SeeAlso{\_U\_dyn\_cancel(3)}

\section{Author}

\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd

\end{document}

<MSG> Replace '%%' with '%' inside verbatim.

(Logical change 1.240)

<DFF> @@ -158,7 +158,7 @@ void show_backtrace (void) {
   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);
+    printf ("ip = %lx, sp = %lx\n", (long) ip, (long) sp);
   }
 }
 \end{verbatim}

{'commit': 'diff --git a/doc/libunwind.tex b/doc/libunwind.tex\nindex 28c03e50..cef6fbbf 100644\n--- a/doc/libunwind.tex\n+++ b/doc/libunwind.tex\n@@ -158,7 +158,7 @@ void show_backtrace (void) {\n   while (unw_step(&cursor) > 0) {\n     unw_get_reg(&cursor, UNW_REG_IP, &ip);\n     unw_get_reg(&cursor, UNW_REG_SP, &sp);\n-    printf ("ip = %%lx, sp = %%lx\\n", (long) ip, (long) sp);\n+    printf ("ip = %lx, sp = %lx\\n", (long) ip, (long) sp);\n   }\n }\n \\end{verbatim}\n', 'commit_subject': "Replace '%%' with '%' inside verbatim.", 'repo_name': 'libunwind/libunwind', 'committer': {'name': '(none)!davidm', 'email': '(none)!davidm', 'time_sec': '1091696397', 'tz_offset': '0', 'date': {'seconds': '1091696397'}}, 'commit_tree': '3efeb8d62f3e1046167ef79a95d58fdda888bd9c', 'commit_message': "Replace '%%' with '%' inside verbatim.\n\n(Logical change 1.240)\n", 'language_name': 'C', 'license': 'mit', 'hunks': '@@ -158,7 +158,7 @@ void show_backtrace (void) {\n   while (unw_step(&cursor) > 0) {\n     unw_get_reg(&cursor, UNW_REG_IP, &ip);\n     unw_get_reg(&cursor, UNW_REG_SP, &sp);\n-    printf ("ip = %%lx, sp = %%lx\\n", (long) ip, (long) sp);\n+    printf ("ip = %lx, sp = %lx\\n", (long) ip, (long) sp);\n   }\n }\n \\end{verbatim}\n', 'addition_count': 1, 'deletion_count': 1, 'src_file': 'a/doc/libunwind.tex', 'tgt_file': 'b/doc/libunwind.tex', 'file_extension': '.tex', 'before_file': '\\documentclass{article}\n\\usepackage[fancyhdr,pdf]{latex2man}\n\n\\input{common.tex}\n\n\\begin{document}\n\n\\begin{Name}{3}{libunwind}{David Mosberger-Tang}{Programming Library}{Introduction to libunwind}libunwind -- a (mostly) platform-independent unwind API\n\\end{Name}\n\n\\section{Synopsis}\n\n\\File{\\#include $<$libunwind.h$>$}\\\\\n\n\\noindent\n\\Type{int} \\Func{unw\\_getcontext}(\\Type{unw\\_context\\_t~*});\\\\\n\\noindent\n\\Type{int} \\Func{unw\\_init\\_local}(\\Type{unw\\_cursor\\_t~*}, \\Type{unw\\_context\\_t~*});\\\\\n\\noindent\n\\Type{int} \\Func{unw\\_init\\_remote}(\\Type{unw\\_cursor\\_t~*}, \\Type{unw\\_addr\\_space\\_t}, \\Type{void~*});\\\\\n\\noindent\n\\Type{int} \\Func{unw\\_step}(\\Type{unw\\_cursor\\_t~*});\\\\\n\\noindent\n\\Type{int} \\Func{unw\\_get\\_reg}(\\Type{unw\\_cursor\\_t~*}, \\Type{unw\\_regnum\\_t}, \\Type{unw\\_word\\_t~*});\\\\\n\\noindent\n\\Type{int} \\Func{unw\\_get\\_fpreg}(\\Type{unw\\_cursor\\_t~*}, \\Type{unw\\_regnum\\_t}, \\Type{unw\\_fpreg\\_t~*});\\\\\n\\noindent\n\\Type{int} \\Func{unw\\_set\\_reg}(\\Type{unw\\_cursor\\_t~*}, \\Type{unw\\_regnum\\_t}, \\Type{unw\\_word\\_t});\\\\\n\\noindent\n\\Type{int} \\Func{unw\\_set\\_fpreg}(\\Type{unw\\_cursor\\_t~*}, \\Type{unw\\_regnum\\_t}, \\Type{unw\\_fpreg\\_t});\\\\\n\\noindent\n\\Type{int} \\Func{unw\\_resume}(\\Type{unw\\_cursor\\_t~*});\\\\\n\n\\noindent\n\\Type{unw\\_addr\\_space\\_t} \\Var{unw\\_local\\_addr\\_space};\\\\\n\\noindent\n\\Type{unw\\_addr\\_space\\_t} \\Func{unw\\_create\\_addr\\_space}(\\Type{unw\\_accessors\\_t}, \\Type{int});\\\\\n\\noindent\n\\Type{void} \\Func{unw\\_destroy\\_addr\\_space}(\\Type{unw\\_addr\\_space\\_t});\\\\\n\\noindent\n\\Type{unw\\_accessors\\_t} \\Func{unw\\_get\\_accessors}(\\Type{unw\\_addr\\_space\\_t});\\\\\n\\noindent\n\\Type{void} \\Func{unw\\_flush\\_cache}(\\Type{unw\\_addr\\_space\\_t}, \\Type{unw\\_word\\_t}, \\Type{unw\\_word\\_t});\\\\\n\\noindent\n\\Type{int} \\Func{unw\\_set\\_caching\\_policy}(\\Type{unw\\_addr\\_space\\_t}, \\Type{unw\\_caching\\_policy\\_t});\\\\\n\\noindent\n\\Type{int} \\Func{unw\\_set\\_cache\\_size}(\\Type{unw\\_addr\\_space\\_t}, \\Type{size\\_t}, \\Type{int});\\\\\n\n\\noindent\n\\Type{const char *}\\Func{unw\\_regname}(\\Type{unw\\_regnum\\_t});\\\\\n\\noindent\n\\Type{int} \\Func{unw\\_get\\_proc\\_info}(\\Type{unw\\_cursor\\_t~*}, \\Type{unw\\_proc\\_info\\_t~*});\\\\\n\\noindent\n\\Type{int} \\Func{unw\\_get\\_save\\_loc}(\\Type{unw\\_cursor\\_t~*}, \\Type{int}, \\Type{unw\\_save\\_loc\\_t~*});\\\\\n\\noindent\n\\Type{int} \\Func{unw\\_is\\_fpreg}(\\Type{unw\\_regnum\\_t});\\\\\n\\Type{int} \\Func{unw\\_is\\_signal\\_frame}(\\Type{unw\\_cursor\\_t~*});\\\\\n\\noindent\n\\Type{int} \\Func{unw\\_get\\_proc\\_name}(\\Type{unw\\_cursor\\_t~*}, \\Type{char~*}, \\Type{size\\_t}, \\Type{unw\\_word\\_t~*});\\\\\n\n\\noindent\n\\Type{void} \\Func{\\_U\\_dyn\\_register}(\\Type{unw\\_dyn\\_info\\_t~*});\\\\\n\\noindent\n\\Type{void} \\Func{\\_U\\_dyn\\_cancel}(\\Type{unw\\_dyn\\_info\\_t~*});\\\\\n\n\\section{Local Unwinding}\n\n\\Prog{Libunwind} is very easy to use when unwinding a stack from\nwithin a running program.  This is called \\emph{local} unwinding.  Say\nyou want to unwind the stack while executing in some function\n\\Func{F}().  In this function, you would call \\Func{unw\\_getcontext}()\nto get a snapshot of the CPU registers (machine-state).  Then you\ninitialize an \\emph{unwind~cursor} based on this snapshot.  This is\ndone with a call to \\Func{unw\\_init\\_local}().  The cursor now points\nto the current frame, that is, the stack frame that corresponds to the\ncurrent activation of function \\Func{F}().  The unwind cursor can then\nbe moved ``up\'\' (towards earlier stack frames) by calling\n\\Func{unw\\_step}().  By repeatedly calling this routine, you can\nuncover the entire call-chain that led to the activation of function\n\\Func{F}().  A positive return value from \\Func{unw\\_step}() indicates\nthat there are more frames in the chain, zero indicates that the end\nof the chain has been reached, and any negative value indicates that\nsome sort of error has occurred.\n\nWhile it is not possible to directly move the unwind cursor in the\n``down\'\' direction (towards newer stack frames), this effect can be\nachieved by making copies of an unwind cursor.  For example, a program\nthat sometimes has to move ``down\'\' by one stack frame could maintain\ntwo cursor variables: ``\\Var{curr}\'\' and ``\\Var{prev}\'\'.  The former\nwould be used as the current cursor and \\Var{prev} would be maintained\nas the ``previous frame\'\' cursor by copying the contents of \\Var{curr}\nto \\Var{prev} right before calling \\Func{unw\\_step}().  With this\napproach, the program could move one step ``down\'\' simply by copying\nback \\Var{prev} to \\Var{curr} whenever that is necessary.  In the most\nextreme case, a program could maintain a separate cursor for each call\nframe and that way it could move up and down the callframe-chain at\nwill.\n\nGiven an unwind cursor, it is possible to read and write the CPU\nregisters that were preserved for the current stack frame (as\nidentified by the cursor).  \\Prog{Libunwind} provides several routines\nfor this purpose: \\Func{unw\\_get\\_reg}() reads an integer (general)\nregister, \\Func{unw\\_get\\_fpreg}() reads a floating-point register,\n\\Func{unw\\_set\\_reg}() writes an integer register, and\n\\Func{unw\\_set\\_fpreg}() writes a floating-point register.  Note that,\nby definition, only the \\emph{preserved} machine state can be accessed\nduring an unwind operation.  Normally, this state consists of the\n\\emph{callee-saved} (``preserved\'\') registers.  However, in some\nspecial circumstances (e.g., in a signal handler trampoline), even the\n\\emph{caller-saved} (``scratch\'\') registers are preserved in the stack\nframe and, in those cases, \\Prog{libunwind} will grant access to them\nas well.  The exact set of registers that can be accessed via the\ncursor depends, of course, on the platform.  However, there are two\nregisters that can be read on all platforms: the instruction pointer\n(IP), sometimes also known as the ``program counter\'\', and the stack\npointer (SP).  In \\Prog{libunwind}, these registers are identified by\nthe macros \\Const{UNW\\_REG\\_IP} and \\Const{UNW\\_REG\\_SP},\nrespectively.\n\nBesides just moving the unwind cursor and reading/writing saved\nregisters, \\Prog{libunwind} also provides the ability to resume\nexecution at an arbitrary stack frame.  As you might guess, this is\nuseful for implementing non-local gotos and the exception handling\nneeded by some high-level languages such as Java.  Resuming execution\nwith a particular stack frame simply requires calling\n\\Func{unw\\_resume}() and passing the cursor identifying the target\nframe as the only argument.\n\nNormally, \\Prog{libunwind} supports both local and remote unwinding\n(the latter will be explained in the next section).  However, if you\ntell \\Prog{libunwind} that your program only needs local unwinding, then\na special implementation can be selected which may run much faster than\nthe generic implementation which supports both kinds of unwinding.  To\nselect this optimized version, simply define the macro\n\\Const{UNW\\_LOCAL\\_ONLY} before including the headerfile\n\\File{$<$libunwind.h$>$}.  It is perfectly OK for a single program to\nemploy both local-only and generic unwinding.  That is, whether or not\n\\Const{UNW\\_LOCAL\\_ONLY} is defined is a choice that each source-file\n(compilation-unit) can make on its own.  Independent of the setting(s)\nof \\Const{UNW\\_LOCAL\\_ONLY}, you\'ll always link the same library into\nthe program (normally \\Opt{-l}\\File{unwind}).  Furthermore, the\nportion of \\Prog{libunwind} that manages unwind-info for dynamically\ngenerated code is not affected by the setting of\n\\Const{UNW\\_LOCAL\\_ONLY}.\n\nIf we put all of the above together, here is how we could use\n\\Prog{libunwind} to write a function ``\\Func{show\\_backtrace}()\'\'\nwhich prints a classic stack trace:\n\n\\begin{verbatim}\n#define UNW_LOCAL_ONLY\n#include <libunwind.h>\n\nvoid show_backtrace (void) {\n  unw_cursor_t cursor; unw_context_t uc;\n  unw_word_t ip, sp;\n\n  while (unw_step(&cursor) > 0) {\n    unw_get_reg(&cursor, UNW_REG_IP, &ip);\n    unw_get_reg(&cursor, UNW_REG_SP, &sp);\n    printf ("ip = %%lx, sp = %%lx\\n", (long) ip, (long) sp);\n  }\n}\n\\end{verbatim}\n}\n\\end{verbatim}\n\n\n\\section{Remote Unwinding}\n\n\\Prog{Libunwind} can also be used to unwind a stack in a ``remote\'\'\nprocess.  Here, ``remote\'\' may mean another process on the same\nmachine or even a process on a completely different machine from the\none that is running \\Prog{libunwind}.  Remote unwinding is typically\nused by debuggers and instruction-set simulators, for example.\n\nBefore you can unwind a remote process, you need to create a new\naddress-space object for that process.  This is achieved with the\n\\Func{unw\\_create\\_addr\\_space}() routine.  The routine takes two\narguments: a pointer to a set of \\emph{accessor} routines and an\ninteger that specifies the byte-order of the target process.  The\naccessor routines provide \\Func{libunwind} with the means to\ncommunicate with the remote process.  In particular, there are\ncallbacks to read and write the process\'s memory, its registers, and\nto access unwind information which may be needed by \\Func{libunwind}.\n\nWith the address space created, unwinding can be initiated by a call\nto \\Func{unw\\_init\\_remote}().  This routine is very similar to\n\\Func{unw\\_init\\_local}(), except that it takes an address-space\nobject and an opaque pointer as arguments.  The routine uses these\narguments to fetch the initial machine state.  \\Prog{Libunwind} never\nuses the opaque pointer on its own, but instead just passes it on to\nthe accessor (callback) routines.  Typically, this pointer is used to\nselect, e.g., the thread within a process that is to be unwound.\n\nOnce a cursor has been initialized with \\Func{unw\\_init\\_remote}(),\nunwinding works exactly like in the local case.  That is, you can use\n\\Func{unw\\_step}() to move ``up\'\' in the call-chain, read and write\nregisters, or resume execution at a particular stack frame by calling\n\\Func{unw\\_resume}.\n\n\n\\section{Cross-platform and Multi-platform Unwinding}\n\n\\Prog{Libunwind} has been designed to enable unwinding across\nplatforms (architectures).  Indeed, a single program can use\n\\Prog{libunwind} to unwind an arbitrary number of target platforms,\nall at the same time!\n\nWe call the machine that is running \\Prog{libunwind} the \\emph{host}\nand the machine that is running the process being unwound the\n\\emph{target}.  If the host and the target platform are the same, we\ncall it \\emph{native} unwinding.  If they differ, we call it\n\\emph{cross-platform} unwinding.\n\nThe principle behind supporting native, cross-platform, and\nmulti-platform unwinding is very simple: for native unwinding, a\nprogram includes \\File{$<$libunwind.h$>$} and uses the linker switch\n\\Opt{-l}\\File{unwind}.  For cross-platform unwinding, a program\nincludes \\File{$<$libunwind-}\\Var{PLAT}\\File{.h$>$} and uses the linker\nswitch \\Opt{-l}\\File{unwind-}\\Var{PLAT}, where \\Var{PLAT} is the name\nof the target platform (e.g., \\File{ia64} for IA-64, \\File{hppa-elf}\nfor ELF-based HP PA-RISC, or \\File{x86} for 80386).  Multi-platform\nunwinding works exactly like cross-platform unwinding, the only\nlimitation is that a single source file (compilation unit) can include\nat most one \\Prog{libunwind} header file.  In other words, the\nplatform-specific support for each supported target needs to be\nisolated in separate source files---a limitation that shouldn\'t be an\nissue in practice.\n\nNote that, by definition, local unwinding is possible only for the\nnative case.  Attempting to call, e.g., \\Func{unw\\_local\\_init}() when\ntargeting a cross-platform will result in a link-time error\n(unresolved references).\n\n\n\\section{Thread- and Signal-Safety}\n\n\nAll \\Prog{libunwind} routines are thread-safe.  What this means is\nthat multiple threads may use \\Prog{libunwind} simultaneously.\nHowever, any given cursor may be accessed by only one thread at\nany given time.\n\nTo ensure thread-safety, some \\Prog{libunwind} routines may have to\nuse locking.  Such routines \\emph{must~not} be called from signal\nhandlers (directly or indirectly) and are therefore \\emph{not}\nsignal-safe.  The manual page for each \\Prog{libunwind} routine\nidentifies whether or not it is signal-safe, but as a general rule,\nany routine that may be needed for \\emph{local} unwinding is\nsignal-safe (e.g., \\Func{unw\\_step}() for local unwinding is\nsignal-safe).  For remote-unwinding, \\emph{none} of the\n\\Prog{libunwind} routines are guaranteed to be signal-safe.\n\n\n\\section{Unwinding Through Dynamically Generated Code}\n\n\\Func{Libunwind} provides the routines \\Func{\\_U\\_dyn\\_register}() and\n\\Func{\\_U\\_dyn\\_cancel}() to register/cancel the information required to\nunwind through code that has been generated at runtime (e.g., by a\njust-in-time (JIT) compiler).  It is important to register the\ninformation for \\emph{all} dynamically generated code because\notherwise, a debugger may not be able to function properly or\nhigh-level language exception handling may not work as expected.\n\nThe interface for registering and canceling dynamic unwind info has\nbeen designed for maximum efficiency, so as to minimize the\nperformance impact on JIT-compilers.  In particular, both routines are\nguaranteed to execute in ``constant time\'\' (O(1)) and the\ndata-structure encapsulating the dynamic unwind info has been designed\nto facilitate sharing, such that similar procedures can share much of\nthe underlying information.\n\nFor more information on the \\Prog{libunwind} support for dynamically\ngenerated code, see \\SeeAlso{libunwind-dynamic(3)}.\n\n\n\\section{Caching of Unwind Info}\n\nTo speed up execution, \\Prog{libunwind} may aggressively cache the\ninformation it needs to perform unwinding.  If a process changes\nduring its lifetime, this creates a risk of \\Prog{libunwind} using\nstale data.  For example, this would happen if \\Prog{libunwind} were\nto cache information about a shared library which later on gets\nunloaded (e.g., via \\Cmd{dlclose}{3}).\n\nTo prevent the risk of using stale data, \\Prog{libunwind} provides two\nfacilities: first, it is possible to flush the cached information\nassociated with a specific address range in the target process (or the\nentire address space, if desired).  This functionality is provided by\n\\Func{unw\\_flush\\_cache}().  The second facility is provided by\n\\Func{unw\\_set\\_caching\\_policy}(), which lets a program\nselect the exact caching policy in use for a given address-space\nobject.  In particular, by selecting the policy\n\\Const{UNW\\_CACHE\\_NONE}, it is possible to turn off caching\ncompletely, therefore eliminating the risk of stale data altogether\n(at the cost of slower execution).  By default, caching is enabled for\nlocal unwinding only.  The cache size can be dynamically changed with\n\\Func{unw\\_set\\_cache\\_size}(), which also flushes the current cache.\n\n\n\\section{Files}\n\n\\begin{Description}\n\\item[\\File{libunwind.h}] Headerfile to include for native (same\n  platform) unwinding.\n\\item[\\File{libunwind-}\\Var{PLAT}\\File{.h}] Headerfile to include when\n  the unwind target runs on platform \\Var{PLAT}.  For example, to unwind\n  an IA-64 program, the header file \\File{libunwind-ia64.h} should be\n  included.\n\\item[\\Opt{-l}\\File{unwind}] Linker-switch to add when building a\n  program that does native (same platform) unwinding.\n\\item[\\Opt{-l}\\File{unwind-}\\Var{PLAT}] Linker-switch to add when\n  building a program that unwinds a program on platform \\Var{PLAT}.\n  For example, to (cross-)unwind an IA-64 program, the linker switch\n  \\File{-lunwind-ia64} should be added.  Note: multiple such switches\n  may need to be specified for programs that can unwind programs on\n  multiple platforms.\n\\end{Description}\n\n\\section{See Also}\n\n\\SeeAlso{libunwind-dynamic(3)},\n\\SeeAlso{libunwind-ia64(3)},\n\\SeeAlso{libunwind-ptrace(3)},\n\\SeeAlso{libunwind-setjmp(3)},\n\\SeeAlso{unw\\_create\\_addr\\_space(3)},\n\\SeeAlso{unw\\_destroy\\_addr\\_space(3)},\n\\SeeAlso{unw\\_flush\\_cache(3)},\n\\SeeAlso{unw\\_get\\_accessors(3)},\n\\SeeAlso{unw\\_get\\_fpreg(3)},\n\\SeeAlso{unw\\_get\\_proc\\_info(3)},\n\\SeeAlso{unw\\_get\\_proc\\_name(3)},\n\\SeeAlso{unw\\_get\\_reg(3)},\n\\SeeAlso{unw\\_getcontext(3)},\n\\SeeAlso{unw\\_init\\_local(3)},\n\\SeeAlso{unw\\_init\\_remote(3)},\n\\SeeAlso{unw\\_is\\_fpreg(3)},\n\\SeeAlso{unw\\_is\\_signal\\_frame(3)},\n\\SeeAlso{unw\\_regname(3)},\n\\SeeAlso{unw\\_resume(3)},\n\\SeeAlso{unw\\_set\\_caching\\_policy(3)},\n\\SeeAlso{unw\\_set\\_cache\\_size(3)},\n\\SeeAlso{unw\\_set\\_fpreg(3)},\n\\SeeAlso{unw\\_set\\_reg(3)},\n\\SeeAlso{unw\\_step(3)},\n\\SeeAlso{unw\\_strerror(3)},\n\\SeeAlso{\\_U\\_dyn\\_register(3)},\n\\SeeAlso{\\_U\\_dyn\\_cancel(3)}\n\n\\section{Author}\n\n\\noindent\nDavid Mosberger-Tang\\\\\nEmail: \\Email{dmosberger@gmail.com}\\\\\nWWW: \\URL{http://www.nongnu.org/libunwind/}.\n\\LatexManEnd\n\n\\end{document}\n', 'message': "Replace '%%' with '%' inside verbatim.\n\n(Logical change 1.240)\n", 'author_name': '(none)!davidm', 'lang': 'tex'}