unw_resume −− resume execution in a particular stack frame
#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(3), unw_set_reg(3), sigprocmask(2)
David
Mosberger−Tang
Email: [email protected]
WWW: http://www.nongnu.org/libunwind/.