1 files changed, 99 insertions, 0 deletions
diff --git a/src/third_party/unwind/dist/doc/unw_resume.tex b/src/third_party/unwind/dist/doc/unw_resume.tex
new file mode 100644
index 00000000000..38b18248ab6
--- /dev/null
+++ b/src/third_party/unwind/dist/doc/unw_resume.tex
@@ -0,0 +1,99 @@
+\documentclass{article}
+\usepackage[fancyhdr,pdf]{latex2man}
+
+\input{common.tex}
+
+\begin{document}
+
+\begin{Name}{3}{unw\_resume}{David Mosberger-Tang}{Programming Library}{unw\_resume}unw\_resume -- resume execution in a particular stack frame
+\end{Name}
+
+\section{Synopsis}
+
+\File{\#include $<$libunwind.h$>$}\\
+
+\Type{int} \Func{unw\_resume}(\Type{unw\_cursor\_t~*}\Var{cp});\\
+
+\section{Description}
+
+The \Func{unw\_resume}() routine resumes execution at the stack frame
+identified by \Var{cp}.  The behavior of this routine differs
+slightly for local and remote unwinding.
+
+For local unwinding, \Func{unw\_resume}() restores the machine state
+and then directly resumes execution in the target stack frame.  Thus
+\Func{unw\_resume}() does not return in this case.  Restoring the
+machine state normally involves restoring the ``preserved''
+(callee-saved) registers.  However, if execution in any of the stack
+frames younger (more deeply nested) than the one identified by
+\Var{cp} was interrupted by a signal, then \Func{unw\_resume}() will
+restore all registers as well as the signal mask.  Attempting to call
+\Func{unw\_resume}() on a cursor which identifies the stack frame of
+another thread results in undefined behavior (e.g., the program may
+crash).
+
+For remote unwinding, \Func{unw\_resume}() installs the machine state
+identified by the cursor by calling the \Func{access\_reg} and
+\Func{access\_fpreg} accessor callbacks as needed.  Once that is
+accomplished, the \Func{resume} accessor callback is invoked.  The
+\Func{unw\_resume} routine then returns normally (that is, unlikely
+for local unwinding, \Func{unw\_resume} will always return for remote
+unwinding).
+
+Most platforms reserve some registers to pass arguments to exception
+handlers (e.g., IA-64 uses \texttt{r15}-\texttt{r18} for this
+purpose).  These registers are normally treated like ``scratch''
+registers.  However, if \Prog{libunwind} is used to set an exception
+argument register to a particular value (e.g., via
+\Func{unw\_set\_reg}()), then \Func{unw\_resume}() will install this
+value as the contents of the register.  In other words, the exception
+handling arguments are installed even in cases where normally only the
+``preserved'' registers are restored.
+
+Note that \Func{unw\_resume}() does \emph{not} invoke any unwind
+handlers (aka, ``personality routines'').  If a program needs this, it
+will have to do so on its own by obtaining the \Type{unw\_proc\_info\_t}
+of each unwound frame and appropriately processing its unwind handler
+and language-specific data area (lsda).  These steps are generally
+dependent on the target-platform and are regulated by the
+processor-specific ABI (application-binary interface).
+
+\section{Return Value}
+
+For local unwinding, \Func{unw\_resume}() does not return on success.
+For remote unwinding, it returns 0 on success.  On failure, the
+negative value of one of the errors below is returned.
+
+\section{Thread and Signal Safety}
+
+\Func{unw\_resume}() is thread-safe.  If cursor \Var{cp} is in the
+local address-space, this routine is also safe to use from a signal
+handler.
+
+\section{Errors}
+
+\begin{Description}
+\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
+\item[\Const{UNW\_EBADREG}] A register needed by \Func{unw\_resume}() wasn't
+  accessible.
+\item[\Const{UNW\_EINVALIDIP}] The instruction pointer identified by
+  \Var{cp} is not valid.
+\item[\Const{UNW\_BADFRAME}] The stack frame identified by
+  \Var{cp} is not valid.
+\end{Description}
+
+\section{See Also}
+
+\SeeAlso{libunwind(3)},
+\SeeAlso{unw\_set\_reg(3)},
+sigprocmask(2)
+
+\section{Author}
+
+\noindent
+David Mosberger-Tang\\
+Email: \Email{dmosberger@gmail.com}\\
+WWW: \URL{http://www.nongnu.org/libunwind/}.
+\LatexManEnd
+
+\end{document}