unw_resume - Man Page

#include <libunwind.h>

int unw_resume(unw_cursor_t *cp);

The unw_resume() routine resumes execution at the stack frame  identified by cp​. The behavior of this routine differs  slightly for local and remote unwinding.

For local unwinding, unw_resume() restores the machine state  and then directly resumes execution in the target stack frame. Thus  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  cp was interrupted by a signal, then unw_resume() will  restore all registers as well as the signal mask. Attempting to call  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, unw_resume() installs the machine state  identified by the cursor by calling the access_reg and  access_fpreg accessor callbacks as needed. Once that is  accomplished, the resume accessor callback is invoked. The  unw_resume routine then returns normally (that is, unlikely  for local unwinding, unw_resume will always return for remote  unwinding).

Most platforms reserve some registers to pass arguments to exception  handlers (e.g., IA-64 uses r15-r18 for this  purpose). These registers are normally treated like “scratch​”  registers. However, if libunwind is used to set an exception  argument register to a particular value (e.g., via  unw_set_reg()), then 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 unw_resume() does 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 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).

For local unwinding, 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.

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

UNW_EUNSPEC

An unspecified error occurred.

UNW_EBADREG

A register needed by unw_resume() wasn​'t  accessible.

UNW_EINVALIDIP

The instruction pointer identified by  cp is not valid.

UNW_BADFRAME

The stack frame identified by  cp is not valid.

libunwind(3libunwind), unw_set_reg(3libunwind), sigprocmask(2)

David Mosberger-Tang
Email: dmosberger@gmail.com
WWW: http://www.nongnu.org/libunwind/​.