blob: 38b18248ab66f24592ccd31fc3d7ac34d8cde16d [file] [log] [blame]
 \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}