unw_resume.tex revision 972aec70ba48f64db9b635a47a497cd65489d343 
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 as well as safe to use from a
70signal handler.
71
72\section{Errors}
73
74\begin{Description}
75\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
76\item[\Const{UNW\_EBADREG}] A register needed by \Func{unw\_resume}() wasn't
77  accessible.
78\item[\Const{UNW\_EINVALIDIP}] The instruction pointer identified by
79  \Var{cp} is not valid.
80\item[\Const{UNW\_BADFRAME}] The stack frame identified by
81  \Var{cp} is not valid.
82\end{Description}
83
84\section{See Also}
85
86\SeeAlso{libunwind(3)},
87\SeeAlso{unw\_set\_reg(3)},
88sigprocmask(2)
89
90\section{Author}
91
92\noindent
93David Mosberger-Tang\\
94Hewlett-Packard Labs\\
95Palo-Alto, CA 94304\\
96Email: \Email{davidm@hpl.hp.com}\\
97WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
98\LatexManEnd
99
100\end{document}
101