unw_resume(3)

1UNW_RESUME(3)                Programming Library                 UNW_RESUME(3)
2
3
4

NAME

6       unw_resume -- resume execution in a particular stack frame
7

SYNOPSIS

9       #include <libunwind.h>
10
11       int unw_resume(unw_cursor_t *cp);
12

DESCRIPTION

14       The  unw_resume()  routine resumes execution at the stack frame identi‐
15       fied by cp.  The behavior of this routine differs  slightly  for  local
16       and remote unwinding.
17
18       For  local  unwinding, unw_resume() restores the machine state and then
19       directly resumes execution in the target stack frame. Thus unw_resume()
20       does  not  return  in  this  case. Restoring the machine state normally
21       involves restoring the ``preserved'' (callee-saved) registers. However,
22       if  execution  in  any of the stack frames younger (more deeply nested)
23       than the one identified  by  cp  was  interrupted  by  a  signal,  then
24       unw_resume()  will  restore  all  registers as well as the signal mask.
25       Attempting to call unw_resume() on a cursor which identifies the  stack
26       frame  of  another thread results in undefined behavior (e.g., the pro‐
27       gram may crash).
28
29       For remote unwinding, unw_resume() installs the machine  state  identi‐
30       fied  by the cursor by calling the access_reg and access_fpreg accessor
31       callbacks as needed. Once that is  accomplished,  the  resume  accessor
32       callback is invoked. The unw_resume routine then returns normally (that
33       is, unlikely for local unwinding, unw_resume  will  always  return  for
34       remote unwinding).
35
36       Most  platforms  reserve  some registers to pass arguments to exception
37       handlers (e.g., IA-64 uses r15-r18 for this purpose).  These  registers
38       are  normally treated like ``scratch'' registers. However, if libunwind
39       is used to set an exception argument register  to  a  particular  value
40       (e.g., via unw_set_reg()), then unw_resume() will install this value as
41       the contents of the register. In other words,  the  exception  handling
42       arguments  are  installed  even in cases where normally only the ``pre‐
43       served'' registers are restored.
44
45       Note that unw_resume() does not invoke any unwind handlers (aka, ``per‐
46       sonality routines''). If a program needs this, it will have to do so on
47       its own by obtaining the unw_proc_info_t  of  each  unwound  frame  and
48       appropriately  processing its unwind handler and language-specific data
49       area (lsda). These steps are generally dependent on the target-platform
50       and  are  regulated  by  the processor-specific ABI (application-binary
51       interface).
52

RETURN VALUE

54       For local unwinding, unw_resume() does  not  return  on  success.   For
55       remote  unwinding,  it  returns  0 on success. On failure, the negative
56       value of one of the errors below is returned.
57

THREAD AND SIGNAL SAFETY

59       unw_resume()  is  thread-safe.  If  cursor   cp   is   in   the   local
60       address-space, this routine is also safe to use from a signal handler.
61

ERRORS

63       UNW_EUNSPEC
64               An unspecified error occurred.
65
66       UNW_EBADREG
67               A register needed by unw_resume() wasn't accessible.
68
69       UNW_EINVALIDIP
70               The instruction pointer identified by cp is not valid.
71
72       UNW_BADFRAME
73               The stack frame identified by cp is not valid.
74

AUTHOR

79       David Mosberger-Tang
80       Hewlett-Packard Labs
81       Palo-Alto, CA 94304
82       Email: davidm@hpl.hp.com
83       WWW: http://www.hpl.hp.com/research/linux/libunwind/.
84
85
86
87Programming Library             05 August 2004                   UNW_RESUME(3)