mirror of
https://github.com/tobast/libunwind-eh_elf.git
synced 2024-11-24 16:27:37 +01:00
101 lines
3.7 KiB
TeX
101 lines
3.7 KiB
TeX
\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\\
|
|
Hewlett-Packard Labs\\
|
|
Palo-Alto, CA 94304\\
|
|
Email: \Email{davidm@hpl.hp.com}\\
|
|
WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
|
|
\LatexManEnd
|
|
|
|
\end{document}
|