1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
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}
|
