doc/unw_resume.tex

   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
  19 The \Func{unw\_resume}() routine resumes execution at the stack frame
  20 identified by \Var{cp}.  The behavior of this routine differs
  21 slightly for local and remote unwinding.
  22
  23 For local unwinding, \Func{unw\_resume}() restores the machine state
  24 and then directly resumes execution in the target stack frame.  Thus
  25 \Func{unw\_resume}() does not return in this case.  Restoring the
  26 machine state normally involves restoring the ``preserved''
  27 (callee-saved) registers.  However, if execution in any of the stack
  28 frames younger (more deeply nested) than the one identified by
  29 \Var{cp} was interrupted by a signal, then \Func{unw\_resume}() will
  30 restore all registers as well as the signal mask.  Attempting to call
  31 \Func{unw\_resume}() on a cursor which identifies the stack frame of
  32 another thread results in undefined behavior (e.g., the program may
  33 crash).
  34
  35 For remote unwinding, \Func{unw\_resume}() installs the machine state
  36 identified by the cursor by calling the \Func{access\_reg} and
  37 \Func{access\_fpreg} accessor callbacks as needed.  Once that is
  38 accomplished, the \Func{resume} accessor callback is invoked.  The
  39 \Func{unw\_resume} routine then returns normally (that is, unlikely
  40 for local unwinding, \Func{unw\_resume} will always return for remote
  41 unwinding).
  42
  43 Most platforms reserve some registers to pass arguments to exception
  44 handlers (e.g., IA-64 uses \texttt{r15}-\texttt{r18} for this
  45 purpose).  These registers are normally treated like ``scratch''
  46 registers.  However, if \Prog{libunwind} is used to set an exception
  47 argument register to a particular value (e.g., via
  48 \Func{unw\_set\_reg}()), then \Func{unw\_resume}() will install this
  49 value as the contents of the register.  In other words, the exception
  50 handling arguments are installed even in cases where normally only the
  51 ``preserved'' registers are restored.
  52
  53 Note that \Func{unw\_resume}() does \emph{not} invoke any unwind
  54 handlers (aka, ``personality routines'').  If a program needs this, it
  55 will have to do so on its own by obtaining the \Type{unw\_proc\_info\_t}
  56 of each unwound frame and appropriately processing its unwind handler
  57 and language-specific data area (lsda).  These steps are generally
  58 dependent on the target-platform and are regulated by the
  59 processor-specific ABI (application-binary interface).
  60
  61 \section{Return Value}
  62
  63 For local unwinding, \Func{unw\_resume}() does not return on success.
  64 For remote unwinding, it returns 0 on success.  On failure, the
  65 negative value of one of the errors below is returned.
  66
  67 \section{Thread and Signal Safety}
  68
  69 \Func{unw\_resume}() is thread-safe.  If cursor \Var{cp} is in the
  70 local address-space, this routine is also safe to use from a signal
  71 handler.
  72
  73 \section{Errors}
  74
  75 \begin{Description}
  76 \item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
  77 \item[\Const{UNW\_EBADREG}] A register needed by \Func{unw\_resume}() wasn't
  78   accessible.
  79 \item[\Const{UNW\_EINVALIDIP}] The instruction pointer identified by
  80   \Var{cp} is not valid.
  81 \item[\Const{UNW\_BADFRAME}] The stack frame identified by
  82   \Var{cp} is not valid.
  83 \end{Description}
  84
  85 \section{See Also}
  86
  87 \SeeAlso{libunwind(3)},
  88 \SeeAlso{unw\_set\_reg(3)},
  89 sigprocmask(2)
  90
  91 \section{Author}
  92
  93 \noindent
  94 David Mosberger-Tang\\
  95 Email: \Email{dmosberger@gmail.com}\\
  96 WWW: \URL{http://www.nongnu.org/libunwind/}.
  97 \LatexManEnd
  98
  99 \end{document}