xref: /external/libunwind/doc/unw_resume.tex

\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}