1\documentclass{article}
2\usepackage[fancyhdr,pdf]{latex2man}
3
4\input{common.tex}
5
6\begin{document}
7
8\begin{Name}{3}{unw\_resume}{David Mosberger-Tang}{Programming Library}{unw\_resume}unw\_resume -- resume execution in a particular stack frame
9\end{Name}
10
11\section{Synopsis}
12
13\File{\#include $<$libunwind.h$>$}\\
14
15\Type{int} \Func{unw\_resume}(\Type{unw\_cursor\_t~*}\Var{cp});\\
16
17\section{Description}
18
19The \Func{unw\_resume}() routine resumes execution at the stack frame
20identified by \Var{cp}.  The behavior of this routine differs
21slightly for local and remote unwinding.
22
23For local unwinding, \Func{unw\_resume}() restores the machine state
24and then directly resumes execution in the target stack frame.  Thus
25\Func{unw\_resume}() does not return in this case.  Restoring the
26machine state normally involves restoring the ``preserved''
27(callee-saved) registers.  However, if execution in any of the stack
28frames younger (more deeply nested) than the one identified by
29\Var{cp} was interrupted by a signal, then \Func{unw\_resume}() will
30restore all registers as well as the signal mask.  Attempting to call
31\Func{unw\_resume}() on a cursor which identifies the stack frame of
32another thread results in undefined behavior (e.g., the program may
33crash).
34
35For remote unwinding, \Func{unw\_resume}() installs the machine state
36identified by the cursor by calling the \Func{access\_reg} and
37\Func{access\_fpreg} accessor callbacks as needed.  Once that is
38accomplished, the \Func{resume} accessor callback is invoked.  The
39\Func{unw\_resume} routine then returns normally (that is, unlikely
40for local unwinding, \Func{unw\_resume} will always return for remote
41unwinding).
42
43Most platforms reserve some registers to pass arguments to exception
44handlers (e.g., IA-64 uses \texttt{r15}-\texttt{r18} for this
45purpose).  These registers are normally treated like ``scratch''
46registers.  However, if \Prog{libunwind} is used to set an exception
47argument register to a particular value (e.g., via
48\Func{unw\_set\_reg}()), then \Func{unw\_resume}() will install this
49value as the contents of the register.  In other words, the exception
50handling arguments are installed even in cases where normally only the
51``preserved'' registers are restored.
52
53Note that \Func{unw\_resume}() does \emph{not} invoke any unwind
54handlers (aka, ``personality routines'').  If a program needs this, it
55will have to do so on its own by obtaining the \Type{unw\_proc\_info\_t}
56of each unwound frame and appropriately processing its unwind handler
57and language-specific data area (lsda).  These steps are generally
58dependent on the target-platform and are regulated by the
59processor-specific ABI (application-binary interface).
60
61\section{Return Value}
62
63For local unwinding, \Func{unw\_resume}() does not return on success.
64For remote unwinding, it returns 0 on success.  On failure, the
65negative value of one of the errors below is returned.
66
67\section{Thread and Signal Safety}
68
69\Func{unw\_resume}() is thread-safe.  If cursor \Var{cp} is in the
70local address-space, this routine is also safe to use from a signal
71handler.
72
73\section{Errors}
74
75\begin{Description}
76\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
77\item[\Const{UNW\_EBADREG}] A register needed by \Func{unw\_resume}() wasn't
78  accessible.
79\item[\Const{UNW\_EINVALIDIP}] The instruction pointer identified by
80  \Var{cp} is not valid.
81\item[\Const{UNW\_BADFRAME}] The stack frame identified by
82  \Var{cp} is not valid.
83\end{Description}
84
85\section{See Also}
86
87\SeeAlso{libunwind(3)},
88\SeeAlso{unw\_set\_reg(3)},
89sigprocmask(2)
90
91\section{Author}
92
93\noindent
94David Mosberger-Tang\\
95Email: \Email{dmosberger@gmail.com}\\
96WWW: \URL{http://www.nongnu.org/libunwind/}.
97\LatexManEnd
98
99\end{document}
100