doc/unw_resume.man

   1 '\" t
   2 .\" Manual page created with latex2man on Thu Aug 16 09:44:45 MDT 2007
   3 .\" NOTE: This file is generated, DO NOT EDIT.
   4 .de Vb
   5 .ft CW
   6 .nf
   7 ..
   8 .de Ve
   9 .ft R
  10
  11 .fi
  12 ..
  13 .TH "UNW\\_RESUME" "3" "16 August 2007" "Programming Library " "Programming Library "
  14 .SH NAME
  15 unw_resume
  16 \-\- resume execution in a particular stack frame
  17 .PP
  18 .SH SYNOPSIS
  19
  20 .PP
  21 #include <libunwind.h>
  22 .br
  23 .PP
  24 int
  25 unw_resume(unw_cursor_t *cp);
  26 .br
  27 .PP
  28 .SH DESCRIPTION
  29
  30 .PP
  31 The unw_resume()
  32 routine resumes execution at the stack frame
  33 identified by cp\&.
  34 The behavior of this routine differs
  35 slightly for local and remote unwinding.
  36 .PP
  37 For local unwinding, unw_resume()
  38 restores the machine state
  39 and then directly resumes execution in the target stack frame. Thus
  40 unw_resume()
  41 does not return in this case. Restoring the
  42 machine state normally involves restoring the ``preserved\&''
  43 (callee\-saved) registers. However, if execution in any of the stack
  44 frames younger (more deeply nested) than the one identified by
  45 cp
  46 was interrupted by a signal, then unw_resume()
  47 will
  48 restore all registers as well as the signal mask. Attempting to call
  49 unw_resume()
  50 on a cursor which identifies the stack frame of
  51 another thread results in undefined behavior (e.g., the program may
  52 crash).
  53 .PP
  54 For remote unwinding, unw_resume()
  55 installs the machine state
  56 identified by the cursor by calling the access_reg
  57 and
  58 access_fpreg
  59 accessor callbacks as needed. Once that is
  60 accomplished, the resume
  61 accessor callback is invoked. The
  62 unw_resume
  63 routine then returns normally (that is, unlikely
  64 for local unwinding, unw_resume
  65 will always return for remote
  66 unwinding).
  67 .PP
  68 Most platforms reserve some registers to pass arguments to exception
  69 handlers (e.g., IA\-64 uses r15\-r18
  70 for this
  71 purpose). These registers are normally treated like ``scratch\&''
  72 registers. However, if libunwind
  73 is used to set an exception
  74 argument register to a particular value (e.g., via
  75 unw_set_reg()),
  76 then unw_resume()
  77 will install this
  78 value as the contents of the register. In other words, the exception
  79 handling arguments are installed even in cases where normally only the
  80 ``preserved\&'' registers are restored.
  81 .PP
  82 Note that unw_resume()
  83 does \fInot\fP
  84 invoke any unwind
  85 handlers (aka, ``personality routines\&''). If a program needs this, it
  86 will have to do so on its own by obtaining the unw_proc_info_t
  87 of each unwound frame and appropriately processing its unwind handler
  88 and language\-specific data area (lsda). These steps are generally
  89 dependent on the target\-platform and are regulated by the
  90 processor\-specific ABI (application\-binary interface).
  91 .PP
  92 .SH RETURN VALUE
  93
  94 .PP
  95 For local unwinding, unw_resume()
  96 does not return on success.
  97 For remote unwinding, it returns 0 on success. On failure, the
  98 negative value of one of the errors below is returned.
  99 .PP
 100 .SH THREAD AND SIGNAL SAFETY
 101
 102 .PP
 103 unw_resume()
 104 is thread\-safe. If cursor cp
 105 is in the
 106 local address\-space, this routine is also safe to use from a signal
 107 handler.
 108 .PP
 109 .SH ERRORS
 110
 111 .PP
 112 .TP
 113 UNW_EUNSPEC
 114  An unspecified error occurred.
 115 .TP
 116 UNW_EBADREG
 117  A register needed by unw_resume()
 118 wasn\&'t
 119 accessible.
 120 .TP
 121 UNW_EINVALIDIP
 122  The instruction pointer identified by
 123 cp
 124 is not valid.
 125 .TP
 126 UNW_BADFRAME
 127  The stack frame identified by
 128 cp
 129 is not valid.
 130 .PP
 131 .SH SEE ALSO
 132
 133 .PP
 134 libunwind(3),
 135 unw_set_reg(3),
 136 sigprocmask(2)
 137 .PP
 138 .SH AUTHOR
 139
 140 .PP
 141 David Mosberger\-Tang
 142 .br
 143 Email: \fBdmosberger@gmail.com\fP
 144 .br
 145 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 146 .\" NOTE: This file is generated, DO NOT EDIT.