libunwind-eh_elf/doc/unw_resume.man

'\" t
.\" Manual page created with latex2man on Thu Aug 16 09:44:45 MDT 2007
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R

.fi
..
.TH "UNW\\_RESUME" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_resume
\-\- resume execution in a particular stack frame 
.PP
.SH SYNOPSIS

.PP
#include <libunwind.h>
.br
.PP
int
unw_resume(unw_cursor_t *cp);
.br
.PP
.SH DESCRIPTION

.PP
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. 
.PP
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). 
.PP
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). 
.PP
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. 
.PP
Note that unw_resume()
does \fInot\fP
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). 
.PP
.SH RETURN VALUE

.PP
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. 
.PP
.SH THREAD AND SIGNAL SAFETY

.PP
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. 
.PP
.SH ERRORS

.PP
.TP
UNW_EUNSPEC
 An unspecified error occurred. 
.TP
UNW_EBADREG
 A register needed by unw_resume()
wasn\&'t 
accessible. 
.TP
UNW_EINVALIDIP
 The instruction pointer identified by 
cp
is not valid. 
.TP
UNW_BADFRAME
 The stack frame identified by 
cp
is not valid. 
.PP
.SH SEE ALSO

.PP
libunwind(3),
unw_set_reg(3),
sigprocmask(2) 
.PP
.SH AUTHOR

.PP
David Mosberger\-Tang
.br
Email: \fBdmosberger@gmail.com\fP
.br
WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
.\" NOTE: This file is generated, DO NOT EDIT.