2003-02-08 11:10:59 +01:00
|
|
|
'\" t
|
2003-03-11 02:05:47 +01:00
|
|
|
.\" Manual page created with latex2man on Fri Mar 7 14:31:39 PST 2003
|
2003-02-08 11:10:59 +01:00
|
|
|
.\" NOTE: This file is generated, DO NOT EDIT.
|
|
|
|
|
.de Vb
|
|
|
|
|
.ft CW
|
|
|
|
|
.nf
|
|
|
|
|
..
|
|
|
|
|
.de Ve
|
|
|
|
|
.ft R
|
|
|
|
|
|
|
|
|
|
.fi
|
|
|
|
|
..
|
2003-03-11 02:05:47 +01:00
|
|
|
.TH "UNW\\_RESUME" "3" "07 March 2003" "Programming Library " "Programming Library "
|
2003-02-08 11:10:59 +01:00
|
|
|
.SH NAME
|
|
|
|
|
|
|
|
|
|
.PP
|
|
|
|
|
unw_resume \-\- resume execution in a particular stack frame
|
|
|
|
|
.PP
|
|
|
|
|
.SH SYNOPSIS
|
|
|
|
|
|
|
|
|
|
.PP
|
|
|
|
|
#include <libunwind.h>
|
|
|
|
|
.br
|
|
|
|
|
.PP
|
|
|
|
|
int
|
|
|
|
|
unw_resume(unw_cursor_t *cursor);
|
|
|
|
|
.br
|
|
|
|
|
.PP
|
|
|
|
|
.SH DESCRIPTION
|
|
|
|
|
|
|
|
|
|
.PP
|
|
|
|
|
The unw_resume()
|
|
|
|
|
routine resumes execution at the stack frame
|
|
|
|
|
identified by cursor\&.
|
2003-02-22 04:08:22 +01:00
|
|
|
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
|
2003-02-08 11:10:59 +01:00
|
|
|
unw_resume()
|
2003-02-22 04:08:22 +01:00
|
|
|
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
|
|
|
|
|
cursor
|
|
|
|
|
was interrupted by a signal, then unw_resume()
|
2003-03-06 07:14:36 +01:00
|
|
|
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).
|
2003-02-22 04:08:22 +01:00
|
|
|
.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).
|
2003-02-08 11:10:59 +01:00
|
|
|
.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
|
2003-02-22 04:08:22 +01:00
|
|
|
is used to set an exception
|
|
|
|
|
argument register to a particular value (e.g., via
|
|
|
|
|
unw_set_reg()),
|
2003-02-08 11:10:59 +01:00
|
|
|
then unw_resume()
|
2003-02-22 04:08:22 +01:00
|
|
|
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
|
2003-02-08 11:10:59 +01:00
|
|
|
``preserved\&'' registers are restored.
|
|
|
|
|
.PP
|
2003-02-21 08:36:26 +01:00
|
|
|
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
|
2003-02-08 11:10:59 +01:00
|
|
|
.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
|
2003-03-11 02:05:47 +01:00
|
|
|
.SH THREAD AND SIGNAL SAFETY
|
|
|
|
|
|
|
|
|
|
.PP
|
|
|
|
|
unw_resume()
|
|
|
|
|
is thread\-safe as well as safe to use from a
|
|
|
|
|
signal handler.
|
|
|
|
|
.PP
|
2003-02-08 11:10:59 +01:00
|
|
|
.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
|
|
|
|
|
cursor
|
|
|
|
|
is not valid.
|
|
|
|
|
.TP
|
|
|
|
|
UNW_BADFRAME
|
|
|
|
|
The stack frame identified by
|
|
|
|
|
cursor
|
|
|
|
|
is not valid.
|
|
|
|
|
.PP
|
|
|
|
|
.SH SEE ALSO
|
|
|
|
|
|
|
|
|
|
.PP
|
|
|
|
|
libunwind(3),
|
|
|
|
|
unw_set_reg(3),
|
|
|
|
|
sigprocmask(2)
|
|
|
|
|
.PP
|
|
|
|
|
.SH AUTHOR
|
|
|
|
|
|
|
|
|
|
.PP
|
|
|
|
|
David Mosberger\-Tang
|
|
|
|
|
.br
|
|
|
|
|
Hewlett\-Packard Labs
|
|
|
|
|
.br
|
|
|
|
|
Palo\-Alto, CA 94304
|
|
|
|
|
.br
|
|
|
|
|
Email: \fBdavidm@hpl.hp.com\fP
|
|
|
|
|
.br
|
|
|
|
|
WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&.
|
|
|
|
|
.\" NOTE: This file is generated, DO NOT EDIT.
|
