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