unw_resume.tex revision 824d6619b500a86ff2fc680268357f0215d59b0c 
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}.  Normally, this is accomplished by
23restoring the ``preserved'' (callee-saved) machine state.  However, if
24execution in any of the stack frames younger (more deeply nested) than
25the one identified by \Var{cursor} was interrupted by a signal, then
26\Func{unw\_resume}() will restore the entire machine state, including
27the ``preserved'' and ``scratch'' (caller-saved) registers, as well as
28the signal mask.
29
30Most platforms reserve some registers to pass arguments to exception
31handlers (e.g., IA-64 uses \texttt{r15}-\texttt{r18} for this
32purpose).  These registers are normally treated like ``scratch''
33registers.  However, if \Prog{libunwind} is used to define an
34exception argument register, e.g., by calling \Func{unw\_set\_reg}(),
35then \Func{unw\_resume}() will always install the new value as the
36contents of that register.  In other words, the exception handling
37arguments are installed even in cases where normally only the
38``preserved'' registers are restored.
39
40\section{Return Value}
41
42For local unwinding, \Func{unw\_resume}() does not return on success.
43For remote unwinding, it returns 0 on success.  On failure, the
44negative value of one of the errors below is returned.
45
46\section{Errors}
47
48\begin{Description}
49\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
50\item[\Const{UNW\_EBADREG}] A register needed by \Func{unw\_resume}() wasn't
51  accessible.
52\item[\Const{UNW\_EINVALIDIP}] The instruction pointer identified by
53  \Var{cursor} is not valid.
54\item[\Const{UNW\_BADFRAME}] The stack frame identified by
55  \Var{cursor} is not valid.
56\end{Description}
57
58\section{See Also}
59
60\SeeAlso{libunwind(3)},
61\SeeAlso{unw\_set\_reg(3)},
62sigprocmask(2)
63
64\section{Author}
65
66\noindent
67David Mosberger-Tang\\
68Hewlett-Packard Labs\\
69Palo-Alto, CA 94304\\
70Email: \Email{davidm@hpl.hp.com}\\
71WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
72\LatexManEnd
73
74\end{document}
75