ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-06-22 00:57:21 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Initial release of Intel SGX for Linux.

Browse Source 
This release is used in conjunction with the linux-sgx-driver Intial release:
https://github.com/01org/linux-sgx-driver
commit-id: 0e865ce5e6b297a787bcdc12d98bada8174be6d7

Intel-id: 33399

Signed-off-by: Angie Chinchilla <angie.v.chinchilla@intel.com>
This commit is contained in:
Angie Chinchilla
2016-06-23 18:51:53 -04:00
parent ba82cfcbb0
commit 9441de4c38
2767 changed files with 820699 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

71
sdk/cpprt/linux/libunwind/doc/Makefile.am Normal file
View File

@ -0,0 +1,71 @@
# man pages that go into section 3:
man3_MANS = libunwind.man libunwind-dynamic.man libunwind-ia64.man \
libunwind-ptrace.man libunwind-setjmp.man \
unw_flush_cache.man \
unw_get_accessors.man \
unw_get_proc_info.man \
unw_get_proc_info_by_ip.man \
unw_get_proc_name.man \
unw_get_fpreg.man \
unw_get_reg.man \
unw_getcontext.man \
unw_init_local.man unw_init_remote.man \
unw_is_fpreg.man \
unw_is_signal_frame.man \
unw_create_addr_space.man \
unw_destroy_addr_space.man \
unw_regname.man unw_resume.man \
unw_set_caching_policy.man \
unw_set_fpreg.man \
unw_set_reg.man \
unw_step.man \
unw_strerror.man \
_U_dyn_register.man \
_U_dyn_cancel.man
EXTRA_DIST = NOTES libunwind.trans \
libunwind.tex libunwind-dynamic.tex libunwind-ia64.tex \
libunwind-ptrace.tex libunwind-setjmp.tex \
unw_flush_cache.tex \
unw_get_accessors.tex \
unw_get_proc_info.tex \
unw_get_proc_info_by_ip.tex \
unw_get_proc_name.tex \
unw_get_fpreg.tex \
unw_get_reg.tex \
unw_getcontext.tex \
unw_init_local.tex unw_init_remote.tex \
unw_is_fpreg.tex \
unw_is_signal_frame.tex \
unw_create_addr_space.tex unw_destroy_addr_space.tex \
unw_regname.tex unw_resume.tex unw_set_caching_policy.tex \
unw_set_fpreg.tex \
unw_set_reg.tex \
unw_step.tex \
unw_strerror.tex \
_U_dyn_register.tex \
_U_dyn_cancel.tex \
$(man3_MANS)
L2M = latex2man
L2P = pdflatex
L2M_CMD = $(L2M) -t $(srcdir)/libunwind.trans
L2H_CMD = $(L2M) -H -t $(srcdir)/libunwind.trans
.tex.man:
$(L2M_CMD) $< $@
-cp $@ $(srcdir)/$@
html:
for n in $(man3_MANS); do \
page=`basename $$n .man`; \
$(L2H_CMD) $(srcdir)/$$page.tex "$$page(3).raw"; \
done
pdf:
for n in $(man3_MANS); do \
page=`basename $$n .man`; \
$(L2P) $(srcdir)/$$page.tex "$$page(3).pdf"; \
done
MAINTAINERCLEANFILES = Makefile.in

127
sdk/cpprt/linux/libunwind/doc/NOTES Normal file
View File

@ -0,0 +1,127 @@
The central data structure of the unwind API is the unwind cursor.
This structure tracks the register contents. The unwind API defines a
handful of well-known frame "registers":
- ip: the instruction pointer (pc)
- rp: the return pointer (rp, aka "return address" or "return link")
- sp: the stack pointer (memory stack pointer, in the case of ia64)
- fp: the frame pointer
- first_ip: the starting address of the current "procedure"
- handler: a pointer to an architecture & language-specific
"personality" routine
- lsda: a pointer to an architecture & language-specific
data-area
The API defines no well-known preserved registers. Each architecture
can define additional registers as needed. Of course, a portable
application may only rely on well-known registers. The names for
preserved registers are defined in the architecture-specific header
file <unwind-ARCH.h>. For example, to get the IA-64-specific register
names, an application would do:
#include <unwind-ia64.h>
The API is designed to handle two primary cases: unwinding within the
current (local) process and unwinding of another ("remote") process
(e.g., through ptrace()). In the local case, the initial machine
state is captured by an unwind context (currently the same as
ucontext_t). In the remote case, the initial machine state is
captured by an unwind accessor structure, which provides callback
routines for reading/writing memory and registers and for obtaining
unwind information.
Once a cursor has been initialized, you can step through the call
chain with the unw_step() routine. The frame registers and the
preserved state can then be accessed with unw_get_reg() or modified
with unw_set_reg(). For floating-point registers, there are separate
unw_get_fpreg() and unw_set_fpreg() routines (on some arches, e.g.,
Alpha, these could be just aliases for unw_{g,s}et_reg()). The
unw_resume() routine can be used to resume execution at an arbitrary
point in the call-chain (as identified by an unwind cursor). This is
intended for exception handling and, at least for now, the intention
is to support this routine only for the local case. Kevin, if you
feel gdb could benefit from such a routine, I'd be interested to hear
about it.
Note that it is perfectly legal to make copies of the unwind cursor.
This makes it possible, e.g., to obtain an unwind context, modify the
state in an earlier call frame, and then resume execution at the point
at which the unwind context was captured.
Here is a quick example of how to use the unwind API to do a simple
stack trace:
unw_cursor_t cursor;
unw_word_t ip, sp;
unw_context_t uc;
unw_getcontext(&uc);
unw_init_local(&cursor, &uc);
do
{
unw_get_reg(&cursor, UNW_REG_IP, &ip);
unw_get_reg(&cursor, UNW_REG_SP, &sp);
printf ("ip=%016lx sp=%016lx\n", ip, sp);
}
while (unw_step (&cursor) > 0);
Note that this particular example should work on pretty much any
architecture, as it doesn't rely on any arch-specific registers.
* Multiarchitecture support
If libunwind is configured for a target other than the local (native)
host, the library is installed as libunwind-$ARCH, where $ARCH is
the target architecture name (e.g., ia32, ia64, or alpha). Similarly,
the header file is installed as libunwind-$ARCH.
With this setup, an application should:
- include <libunwind.h>, and
- link against -lunwind
if the application needs to use the unwinder of the host. An
application wanting to use the unwinder for a different target (e.g.,
a cross-debugger) should:
- include <libunwind-$ARCH.h>, and
- link against -lunwind-$ARCH
The global symbols exported by -lunwind-$ARCH are unique such that the
same application can be linked against the separate unwind libraries
of multiple targets. However, a single compilation unit can include
the header file for only one target. For example, foo.c might include
<libunwind-ia64.h> and bar.c might include <libunwind.h> and the
entire application would have to be linked against both -lunwind and
-lunwind-ia64.
Note: the unwind header files of all targets have a common dependency
on libunwind-common.h. To avoid version conflicts, it is necessary to
ensure that the unwind libraries for all targets were derived from the
same release of libunwind. That is, if the unwind library for one
target is upgraded to a newer version, the libraries for all other
targets also need to be upgraded.
Note 2: The assumption is that a cross-unwinder can handle all
interesting flavors of a target. For example, the unwinder for the
ia64 target is expected to be able to handle both Linux and HP-UX.
* IA-64 Specific Information
Apart from the normal frame-registers, the IA-64 implementation of
libunwind provides the means to access the current value of the
register backing store pointer (bsp). One quirk with this
frame-register is that it corresponds to the address that would be in
register ar.bsp after flushing the current register stack to the
backing store (i.e., as if a "flushrs" instruction had been executed).
Of course, given this value and the contents of the current frame
marker (CFM), it's easy to calculate the original value of ar.bsp:
unw_word_t cfm, bsp, bsp_after_flushrs, sof;
unw_get_reg (&cursor, UNW_IA64_BSP, &bsp_after_flushrs);
unw_get_reg (&cursor, UNW_IA64_CFM, &cfm);
bsp = ia64_rse_skip_regs (bsp_after_flushrs, -(cfm & 0x7f));
** Dynamic Unwind Info

66
sdk/cpprt/linux/libunwind/doc/_U_dyn_cancel.man Normal file
View File

@ -0,0 +1,66 @@
'\" 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 "\\_U\\_DYN\\_CANCEL" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
_U_dyn_cancel
\-\- cancel unwind\-info for dynamically generated code
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
void
_U_dyn_cancel(unw_dyn_info_t *di);
.br
.PP
.SH DESCRIPTION
.PP
The _U_dyn_cancel()
routine cancels the registration of the
unwind\-info for a dynamically generated procedure. Argument di
is the pointer to the unw_dyn_info_t
structure that
describes the procedure\&'s unwind\-info.
.PP
The _U_dyn_cancel()
routine is guaranteed to execute in
constant time (in the absence of contention from concurrent calls to
_U_dyn_register()
or _U_dyn_cancel()).
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
_U_dyn_cancel()
is thread\-safe but \fInot\fP
safe to use
from a signal handler.
.PP
.SH SEE ALSO
.PP
libunwind\-dynamic(3),
_U_dyn_register(3)
.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.

46
sdk/cpprt/linux/libunwind/doc/_U_dyn_cancel.tex Normal file
View File

@ -0,0 +1,46 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{\_U\_dyn\_cancel}{David Mosberger-Tang}{Programming Library}{\_U\_dyn\_cancel}\_U\_dyn\_cancel -- cancel unwind-info for dynamically generated code
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{void} \Func{\_U\_dyn\_cancel}(\Type{unw\_dyn\_info\_t~*}\Var{di});\\
\section{Description}
The \Func{\_U\_dyn\_cancel}() routine cancels the registration of the
unwind-info for a dynamically generated procedure. Argument \Var{di}
is the pointer to the \Type{unw\_dyn\_info\_t} structure that
describes the procedure's unwind-info.
The \Func{\_U\_dyn\_cancel}() routine is guaranteed to execute in
constant time (in the absence of contention from concurrent calls to
\Func{\_U\_dyn\_register}() or \Func{\_U\_dyn\_cancel}()).
\section{Thread and Signal Safety}
\Func{\_U\_dyn\_cancel}() is thread-safe but \emph{not} safe to use
from a signal handler.
\section{See Also}
\SeeAlso{libunwind-dynamic(3)}, \SeeAlso{\_U\_dyn\_register(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

68
sdk/cpprt/linux/libunwind/doc/_U_dyn_register.man Normal file
View File

@ -0,0 +1,68 @@
'\" 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 "\\_U\\_DYN\\_REGISTER" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
_U_dyn_register
\-\- register unwind\-info for dynamically generated code
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
void
_U_dyn_register(unw_dyn_info_t *di);
.br
.PP
.SH DESCRIPTION
.PP
The _U_dyn_register()
routine registers unwind\-info for a
dynamically generated procedure. The procedure\&'s unwind\-info is
described by a structure of type unw_dyn_info_t
(see
libunwind\-dynamic(3)).
A pointer to this structure is
passed in argument di\&.
.PP
The _U_dyn_register()
routine is guaranteed to execute in
constant time (in the absence of contention from concurrent calls to
_U_dyn_register()
or _U_dyn_cancel()).
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
_U_dyn_register()
is thread\-safe but \fInot\fP
safe to use
from a signal handler.
.PP
.SH SEE ALSO
.PP
libunwind\-dynamic(3),
_U_dyn_cancel(3)
.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.

47
sdk/cpprt/linux/libunwind/doc/_U_dyn_register.tex Normal file
View File

@ -0,0 +1,47 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{\_U\_dyn\_register}{David Mosberger-Tang}{Programming Library}{\_U\_dyn\_register}\_U\_dyn\_register -- register unwind-info for dynamically generated code
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{void} \Func{\_U\_dyn\_register}(\Type{unw\_dyn\_info\_t~*}\Var{di});\\
\section{Description}
The \Func{\_U\_dyn\_register}() routine registers unwind-info for a
dynamically generated procedure. The procedure's unwind-info is
described by a structure of type \Type{unw\_dyn\_info\_t} (see
\SeeAlso{libunwind-dynamic(3)}). A pointer to this structure is
passed in argument \Var{di}.
The \Func{\_U\_dyn\_register}() routine is guaranteed to execute in
constant time (in the absence of contention from concurrent calls to
\Func{\_U\_dyn\_register}() or \Func{\_U\_dyn\_cancel}()).
\section{Thread and Signal Safety}
\Func{\_U\_dyn\_register}() is thread-safe but \emph{not} safe to use
from a signal handler.
\section{See Also}
\SeeAlso{libunwind-dynamic(3)}, \SeeAlso{\_U\_dyn\_cancel(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

11
sdk/cpprt/linux/libunwind/doc/common.tex.in Normal file
View File

@ -0,0 +1,11 @@
\setVersion{@VERSION@}
\sloppy
\newcommand{\Lt}{\symbol{"3C}}
\newcommand{\Gt}{\symbol{"3E}}
\newcommand{\Type}[1]{\File{#1}} % see libunwind.trans
\newcommand{\Func}[1]{\Prog{#1}} % see libunwind.trans
\newcommand{\Var}[1]{\Prog{#1}} % see libunwind.trans
\newcommand{\Const}[1]{\File{#1}} % see libunwind.trans
\newcommand{\SeeAlso}[2]{\File{#1}} % see libunwind.trans

538
sdk/cpprt/linux/libunwind/doc/libunwind-dynamic.man Normal file
View File

@ -0,0 +1,538 @@
'\" t
.\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "LIBUNWIND\-DYNAMIC" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
libunwind\-dynamic
\-\- libunwind\-support for runtime\-generated code
.PP
.SH INTRODUCTION
.PP
For libunwind
to do its job, it needs to be able to reconstruct
the \fIframe state\fP
of each frame in a call\-chain. The frame state
describes the subset of the machine\-state that consists of the
\fIframe registers\fP
(typically the instruction\-pointer and the
stack\-pointer) and all callee\-saved registers (preserved registers).
The frame state describes each register either by providing its
current value (for frame registers) or by providing the location at
which the current value is stored (callee\-saved registers).
.PP
For statically generated code, the compiler normally takes care of
emitting \fIunwind\-info\fP
which provides the minimum amount of
information needed to reconstruct the frame\-state for each instruction
in a procedure. For dynamically generated code, the runtime code
generator must use the dynamic unwind\-info interface provided by
libunwind
to supply the equivalent information. This manual
page describes the format of this information in detail.
.PP
For the purpose of this discussion, a \fIprocedure\fP
is defined to
be an arbitrary piece of \fIcontiguous\fP
code. Normally, each
procedure directly corresponds to a function in the source\-language
but this is not strictly required. For example, a runtime
code\-generator could translate a given function into two separate
(discontiguous) procedures: one for frequently\-executed (hot) code and
one for rarely\-executed (cold) code. Similarly, simple
source\-language functions (usually leaf functions) may get translated
into code for which the default unwind\-conventions apply and for such
code, it is not strictly necessary to register dynamic unwind\-info.
.PP
A procedure logically consists of a sequence of \fIregions\fP\&.
Regions are nested in the sense that the frame state at the end of one
region is, by default, assumed to be the frame state for the next
region. Each region is thought of as being divided into a
\fIprologue\fP,
a \fIbody\fP,
and an \fIepilogue\fP\&.
Each of them
can be empty. If non\-empty, the prologue sets up the frame state for
the body. For example, the prologue may need to allocate some space
on the stack and save certain callee\-saved registers. The body
performs the actual work of the procedure but does not change the
frame state in any way. If non\-empty, the epilogue restores the
previous frame state and as such it undoes or cancels the effect of
the prologue. In fact, a single epilogue may undo the effect of the
prologues of several (nested) regions.
.PP
We should point out that even though the prologue, body, and epilogue
are logically separate entities, optimizing code\-generators will
generally interleave instructions from all three entities. For this
reason, the dynamic unwind\-info interface of libunwind
makes no
distinction whatsoever between prologue and body. Similarly, the
exact set of instructions that make up an epilogue is also irrelevant.
The only point in the epilogue that needs to be described explicitly
by the dynamic unwind\-info is the point at which the stack\-pointer
gets restored. The reason this point needs to be described is that
once the stack\-pointer is restored, all values saved in the
deallocated portion of the stack frame become invalid and hence
libunwind
needs to know about it. The portion of the frame
state not saved on the stack is assume to remain valid through the end
of the region. For this reason, there is usually no need to describe
instructions which restore the contents of callee\-saved registers.
.PP
Within a region, each instruction that affects the frame state in some
fashion needs to be described with an operation descriptor. For this
purpose, each instruction in the region is assigned a unique index.
Exactly how this index is derived depends on the architecture. For
example, on RISC and EPIC\-style architecture, instructions have a
fixed size so it\&'s possible to simply number the instructions. In
contrast, most CISC use variable\-length instruction encodings, so it
is usually necessary to use a byte\-offset as the index. Given the
instruction index, the operation descriptor specifies the effect of
the instruction in an abstract manner. For example, it might express
that the instruction stores calle\-saved register r1
at offset 16
in the stack frame.
.PP
.SH PROCEDURES
.PP
A runtime code\-generator registers the dynamic unwind\-info of a
procedure by setting up a structure of type unw_dyn_info_t
and calling _U_dyn_register(),
passing the address of the
structure as the sole argument. The members of the
unw_dyn_info_t
structure are described below:
.TP
void *next
Private to libunwind\&.
Must not be used
by the application.
.TP
void *prev
Private to libunwind\&.
Must not be used
by the application.
.TP
unw_word_t start_ip
The start\-address of the
instructions of the procedure (remember: procedure are defined to be
contiguous pieces of code, so a single code\-range is sufficient).
.TP
unw_word_t end_ip
The end\-address of the
instructions of the procedure (non\-inclusive, that is,
end_ip\-start_ip
is the size of the procedure in
bytes).
.TP
unw_word_t gp
The global\-pointer value in use
for this procedure. The exact meaing of the global\-pointer is
architecture\-specific and on some architecture, it is not used at
all.
.TP
int32_t format
The format of the unwind\-info.
This member can be one of UNW_INFO_FORMAT_DYNAMIC,
UNW_INFO_FORMAT_TABLE,
or
UNW_INFO_FORMAT_REMOTE_TABLE\&.
.TP
union u
This union contains one sub\-member
structure for every possible unwind\-info format:
.RS
.TP
unw_dyn_proc_info_t pi
This member is used
for format UNW_INFO_FORMAT_DYNAMIC\&.
.TP
unw_dyn_table_info_t ti
This member is used
for format UNW_INFO_FORMAT_TABLE\&.
.TP
unw_dyn_remote_table_info_t rti
This member
is used for format UNW_INFO_FORMAT_REMOTE_TABLE\&.
.RE
.RS
.PP
The format of these sub\-members is described in detail below.
.RE
.PP
.SS PROC\-INFO FORMAT
.PP
This is the preferred dynamic unwind\-info format and it is generally
the one used by full\-blown runtime code\-generators. In this format,
the details of a procedure are described by a structure of type
unw_dyn_proc_info_t\&.
This structure contains the following
members:
.PP
.RE
.TP
unw_word_t name_ptr
The address of a
(human\-readable) name of the procedure or 0 if no such name is
available. If non\-zero, The string stored at this address must be
ASCII NUL terminated. For source languages that use name\-mangling
(such as C++ or Java) the string stored at this address should be
the \fIdemangled\fP
version of the name.
.PP
.TP
unw_word_t handler
The address of the
personality\-routine for this procedure. Personality\-routines are
used in conjunction with exception handling. See the C++ ABI draft
(http://www.codesourcery.com/cxx\-abi/) for an overview and a
description of the personality routine. If the procedure has no
personality routine, handler
must be set to 0.
.PP
.TP
uint32_t flags
A bitmask of flags. At the
moment, no flags have been defined and this member must be
set to 0.
.PP
.TP
unw_dyn_region_info_t *regions
A NULL\-terminated
linked list of region\-descriptors. See section ``Region
descriptors\&'' below for more details.
.PP
.SS TABLE\-INFO FORMAT
.PP
This format is generally used when the dynamically generated code was
derived from static code and the unwind\-info for the dynamic and the
static versions is identical. For example, this format can be useful
when loading statically\-generated code into an address\-space in a
non\-standard fashion (i.e., through some means other than
dlopen()).
In this format, the details of a group of procedures
is described by a structure of type unw_dyn_table_info\&.
This structure contains the following members:
.PP
.TP
unw_word_t name_ptr
The address of a
(human\-readable) name of the procedure or 0 if no such name is
available. If non\-zero, The string stored at this address must be
ASCII NUL terminated. For source languages that use name\-mangling
(such as C++ or Java) the string stored at this address should be
the \fIdemangled\fP
version of the name.
.PP
.TP
unw_word_t segbase
The segment\-base value
that needs to be added to the segment\-relative values stored in the
unwind\-info. The exact meaning of this value is
architecture\-specific.
.PP
.TP
unw_word_t table_len
The length of the
unwind\-info (table_data)
counted in units of words
(unw_word_t).
.PP
.TP
unw_word_t table_data
A pointer to the actual
data encoding the unwind\-info. The exact format is
architecture\-specific (see architecture\-specific sections below).
.PP
.SS REMOTE TABLE\-INFO FORMAT
.PP
The remote table\-info format has the same basic purpose as the regular
table\-info format. The only difference is that when libunwind
uses the unwind\-info, it will keep the table data in the target
address\-space (which may be remote). Consequently, the type of the
table_data
member is unw_word_t
rather than a pointer.
This implies that libunwind
will have to access the table\-data
via the address\-space\&'s access_mem()
call\-back, rather than
through a direct memory reference.
.PP
From the point of view of a runtime\-code generator, the remote
table\-info format offers no advantage and it is expected that such
generators will describe their procedures either with the proc\-info
format or the normal table\-info format. The main reason that the
remote table\-info format exists is to enable the
address\-space\-specific find_proc_info()
callback (see
unw_create_addr_space(3))
to return unwind tables whose
data remains in remote memory. This can speed up unwinding (e.g., for
a debugger) because it reduces the amount of data that needs to be
loaded from remote memory.
.PP
.SH REGIONS DESCRIPTORS
.PP
A region descriptor is a variable length structure that describes how
each instruction in the region affects the frame state. Of course,
most instructions in a region usualy do not change the frame state and
for those, nothing needs to be recorded in the region descriptor. A
region descriptor is a structure of type
unw_dyn_region_info_t
and has the following members:
.TP
unw_dyn_region_info_t *next
A pointer to the
next region. If this is the last region, next
is NULL\&.
.TP
int32_t insn_count
The length of the region in
instructions. Each instruction is assumed to have a fixed size (see
architecture\-specific sections for details). The value of
insn_count
may be negative in the last region of a procedure
(i.e., it may be negative only if next
is NULL).
A
negative value indicates that the region covers the last \fIN\fP
instructions of the procedure, where \fIN\fP
is the absolute value
of insn_count\&.
.TP
uint32_t op_count
The (allocated) length of
the op_count
array.
.TP
unw_dyn_op_t op
An array of dynamic unwind
directives. See Section ``Dynamic unwind directives\&'' for a
description of the directives.
.PP
A region descriptor with an insn_count
of zero is an
\fIempty region\fP
and such regions are perfectly legal. In fact,
empty regions can be useful to establish a particular frame state
before the start of another region.
.PP
A single region list can be shared across multiple procedures provided
those procedures share a common prologue and epilogue (their bodies
may differ, of course). Normally, such procedures consist of a canned
prologue, the body, and a canned epilogue. This could be described by
two regions: one covering the prologue and one covering the epilogue.
Since the body length is variable, the latter region would need to
specify a negative value in insn_count
such that
libunwind
knows that the region covers the end of the procedure
(up to the address specified by end_ip).
.PP
The region descriptor is a variable length structure to make it
possible to allocate all the necessary memory with a single
memory\-allocation request. To facilitate the allocation of a region
descriptors libunwind
provides a helper routine with the
following synopsis:
.PP
size_t
_U_dyn_region_size(int
op_count);
.PP
This routine returns the number of bytes needed to hold a region
descriptor with space for op_count
unwind directives. Note
that the length of the op
array does not have to match exactly
with the number of directives in a region. Instead, it is sufficient
if the op
array contains at least as many entries as there are
directives, since the end of the directives can always be indicated
with the UNW_DYN_STOP
directive.
.PP
.SH DYNAMIC UNWIND DIRECTIVES
.PP
A dynamic unwind directive describes how the frame state changes
at a particular point within a region. The description is in
the form of a structure of type unw_dyn_op_t\&.
This
structure has the following members:
.TP
int8_t tag
The operation tag. Must be one
of the unw_dyn_operation_t
values described below.
.TP
int8_t qp
The qualifying predicate that controls
whether or not this directive is active. This is useful for
predicated architecturs such as IA\-64 or ARM, where the contents of
another (callee\-saved) register determines whether or not an
instruction is executed (takes effect). If the directive is always
active, this member should be set to the manifest constant
_U_QP_TRUE
(this constant is defined for all
architectures, predicated or not).
.TP
int16_t reg
The number of the register affected
by the instruction.
.TP
int32_t when
The region\-relative number of
the instruction to which this directive applies. For example,
a value of 0 means that the effect described by this directive
has taken place once the first instruction in the region has
executed.
.TP
unw_word_t val
The value to be applied by the
operation tag. The exact meaning of this value varies by tag. See
Section ``Operation tags\&'' below.
.PP
It is perfectly legitimate to specify multiple dynamic unwind
directives with the same when
value, if a particular instruction
has a complex effect on the frame state.
.PP
Empty regions by definition contain no actual instructions and as such
the directives are not tied to a particular instruction. By
convention, the when
member should be set to 0, however.
.PP
There is no need for the dynamic unwind directives to appear
in order of increasing when
values. If the directives happen to
be sorted in that order, it may result in slightly faster execution,
but a runtime code\-generator should not go to extra lengths just to
ensure that the directives are sorted.
.PP
IMPLEMENTATION NOTE: should libunwind
implementations for
certain architectures prefer the list of unwind directives to be
sorted, it is recommended that such implementations first check
whether the list happens to be sorted already and, if not, sort the
directives explicitly before the first use. With this approach, the
overhead of explicit sorting is only paid when there is a real benefit
and if the runtime code\-generator happens to generated sorted lists
naturally, the performance penalty is limited to a simple O(N) check.
.PP
.SS OPERATIONS TAGS
.PP
The possible operation tags are defined by enumeration type
unw_dyn_operation_t
which defines the following
values:
.PP
.TP
UNW_DYN_STOP
Marks the end of the dynamic unwind
directive list. All remaining entries in the op
array of the
region\-descriptor are ignored. This tag is guaranteed to have a
value of 0.
.PP
.TP
UNW_DYN_SAVE_REG
Marks an instruction which saves
register reg
to register val\&.
.PP
.TP
UNW_DYN_SPILL_FP_REL
Marks an instruction which
spills register reg
to a frame\-pointer\-relative location. The
frame\-pointer\-relative offset is given by the value stored in member
val\&.
See the architecture\-specific sections for a description
of the stack frame layout.
.PP
.TP
UNW_DYN_SPILL_SP_REL
Marks an instruction which
spills register reg
to a stack\-pointer\-relative location. The
stack\-pointer\-relative offset is given by the value stored in member
val\&.
See the architecture\-specific sections for a description
of the stack frame layout.
.PP
.TP
UNW_DYN_ADD
Marks an instruction which adds
the constant value val
to register reg\&.
To add subtract
a constant value, store the two\&'s\-complement of the value in
val\&.
The set of registers that can be specified for this tag
is described in the architecture\-specific sections below.
.PP
.TP
UNW_DYN_POP_FRAMES
.PP
.TP
UNW_DYN_LABEL_STATE
.PP
.TP
UNW_DYN_COPY_STATE
.PP
.TP
UNW_DYN_ALIAS
.PP
unw_dyn_op_t
.PP
_U_dyn_op_save_reg();
_U_dyn_op_spill_fp_rel();
_U_dyn_op_spill_sp_rel();
_U_dyn_op_add();
_U_dyn_op_pop_frames();
_U_dyn_op_label_state();
_U_dyn_op_copy_state();
_U_dyn_op_alias();
_U_dyn_op_stop();
.PP
.SH IA\-64 SPECIFICS
.PP
\- meaning of segbase member in table\-info/table\-remote\-info format
\- format of table_data in table\-info/table\-remote\-info format
\- instruction size: each bundle is counted as 3 instructions, regardless
of template (MLX)
\- describe stack\-frame layout, especially with regards to sp\-relative
and fp\-relative addressing
\- UNW_DYN_ADD can only add to ``sp\&'' (always a negative value); use
POP_FRAMES otherwise
.PP
.SH SEE ALSO
.PP
libunwind(3),
_U_dyn_register(3),
_U_dyn_cancel(3)
.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.

401
sdk/cpprt/linux/libunwind/doc/libunwind-dynamic.tex Normal file
View File

@ -0,0 +1,401 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{libunwind-dynamic}{David Mosberger-Tang}{Programming Library}{Introduction to dynamic unwind-info}libunwind-dynamic -- libunwind-support for runtime-generated code
\end{Name}
\section{Introduction}
For \Prog{libunwind} to do its job, it needs to be able to reconstruct
the \emph{frame state} of each frame in a call-chain. The frame state
describes the subset of the machine-state that consists of the
\emph{frame registers} (typically the instruction-pointer and the
stack-pointer) and all callee-saved registers (preserved registers).
The frame state describes each register either by providing its
current value (for frame registers) or by providing the location at
which the current value is stored (callee-saved registers).
For statically generated code, the compiler normally takes care of
emitting \emph{unwind-info} which provides the minimum amount of
information needed to reconstruct the frame-state for each instruction
in a procedure. For dynamically generated code, the runtime code
generator must use the dynamic unwind-info interface provided by
\Prog{libunwind} to supply the equivalent information. This manual
page describes the format of this information in detail.
For the purpose of this discussion, a \emph{procedure} is defined to
be an arbitrary piece of \emph{contiguous} code. Normally, each
procedure directly corresponds to a function in the source-language
but this is not strictly required. For example, a runtime
code-generator could translate a given function into two separate
(discontiguous) procedures: one for frequently-executed (hot) code and
one for rarely-executed (cold) code. Similarly, simple
source-language functions (usually leaf functions) may get translated
into code for which the default unwind-conventions apply and for such
code, it is not strictly necessary to register dynamic unwind-info.
A procedure logically consists of a sequence of \emph{regions}.
Regions are nested in the sense that the frame state at the end of one
region is, by default, assumed to be the frame state for the next
region. Each region is thought of as being divided into a
\emph{prologue}, a \emph{body}, and an \emph{epilogue}. Each of them
can be empty. If non-empty, the prologue sets up the frame state for
the body. For example, the prologue may need to allocate some space
on the stack and save certain callee-saved registers. The body
performs the actual work of the procedure but does not change the
frame state in any way. If non-empty, the epilogue restores the
previous frame state and as such it undoes or cancels the effect of
the prologue. In fact, a single epilogue may undo the effect of the
prologues of several (nested) regions.
We should point out that even though the prologue, body, and epilogue
are logically separate entities, optimizing code-generators will
generally interleave instructions from all three entities. For this
reason, the dynamic unwind-info interface of \Prog{libunwind} makes no
distinction whatsoever between prologue and body. Similarly, the
exact set of instructions that make up an epilogue is also irrelevant.
The only point in the epilogue that needs to be described explicitly
by the dynamic unwind-info is the point at which the stack-pointer
gets restored. The reason this point needs to be described is that
once the stack-pointer is restored, all values saved in the
deallocated portion of the stack frame become invalid and hence
\Prog{libunwind} needs to know about it. The portion of the frame
state not saved on the stack is assume to remain valid through the end
of the region. For this reason, there is usually no need to describe
instructions which restore the contents of callee-saved registers.
Within a region, each instruction that affects the frame state in some
fashion needs to be described with an operation descriptor. For this
purpose, each instruction in the region is assigned a unique index.
Exactly how this index is derived depends on the architecture. For
example, on RISC and EPIC-style architecture, instructions have a
fixed size so it's possible to simply number the instructions. In
contrast, most CISC use variable-length instruction encodings, so it
is usually necessary to use a byte-offset as the index. Given the
instruction index, the operation descriptor specifies the effect of
the instruction in an abstract manner. For example, it might express
that the instruction stores calle-saved register \Var{r1} at offset 16
in the stack frame.
\section{Procedures}
A runtime code-generator registers the dynamic unwind-info of a
procedure by setting up a structure of type \Type{unw\_dyn\_info\_t}
and calling \Func{\_U\_dyn\_register}(), passing the address of the
structure as the sole argument. The members of the
\Type{unw\_dyn\_info\_t} structure are described below:
\begin{itemize}
\item[\Type{void~*}next] Private to \Prog{libunwind}. Must not be used
by the application.
\item[\Type{void~*}prev] Private to \Prog{libunwind}. Must not be used
by the application.
\item[\Type{unw\_word\_t} \Var{start\_ip}] The start-address of the
instructions of the procedure (remember: procedure are defined to be
contiguous pieces of code, so a single code-range is sufficient).
\item[\Type{unw\_word\_t} \Var{end\_ip}] The end-address of the
instructions of the procedure (non-inclusive, that is,
\Var{end\_ip}-\Var{start\_ip} is the size of the procedure in
bytes).
\item[\Type{unw\_word\_t} \Var{gp}] The global-pointer value in use
for this procedure. The exact meaing of the global-pointer is
architecture-specific and on some architecture, it is not used at
all.
\item[\Type{int32\_t} \Var{format}] The format of the unwind-info.
This member can be one of \Const{UNW\_INFO\_FORMAT\_DYNAMIC},
\Const{UNW\_INFO\_FORMAT\_TABLE}, or
\Const{UNW\_INFO\_FORMAT\_REMOTE\_TABLE}.
\item[\Type{union} \Var{u}] This union contains one sub-member
structure for every possible unwind-info format:
\begin{description}
\item[\Type{unw\_dyn\_proc\_info\_t} \Var{pi}] This member is used
for format \Const{UNW\_INFO\_FORMAT\_DYNAMIC}.
\item[\Type{unw\_dyn\_table\_info\_t} \Var{ti}] This member is used
for format \Const{UNW\_INFO\_FORMAT\_TABLE}.
\item[\Type{unw\_dyn\_remote\_table\_info\_t} \Var{rti}] This member
is used for format \Const{UNW\_INFO\_FORMAT\_REMOTE\_TABLE}.
\end{description}\
The format of these sub-members is described in detail below.
\end{itemize}
\subsection{Proc-info format}
This is the preferred dynamic unwind-info format and it is generally
the one used by full-blown runtime code-generators. In this format,
the details of a procedure are described by a structure of type
\Type{unw\_dyn\_proc\_info\_t}. This structure contains the following
members:
\begin{description}
\item[\Type{unw\_word\_t} \Var{name\_ptr}] The address of a
(human-readable) name of the procedure or 0 if no such name is
available. If non-zero, The string stored at this address must be
ASCII NUL terminated. For source languages that use name-mangling
(such as C++ or Java) the string stored at this address should be
the \emph{demangled} version of the name.
\item[\Type{unw\_word\_t} \Var{handler}] The address of the
personality-routine for this procedure. Personality-routines are
used in conjunction with exception handling. See the C++ ABI draft
(http://www.codesourcery.com/cxx-abi/) for an overview and a
description of the personality routine. If the procedure has no
personality routine, \Var{handler} must be set to 0.
\item[\Type{uint32\_t} \Var{flags}] A bitmask of flags. At the
moment, no flags have been defined and this member must be
set to 0.
\item[\Type{unw\_dyn\_region\_info\_t~*}\Var{regions}] A NULL-terminated
linked list of region-descriptors. See section ``Region
descriptors'' below for more details.
\end{description}
\subsection{Table-info format}
This format is generally used when the dynamically generated code was
derived from static code and the unwind-info for the dynamic and the
static versions is identical. For example, this format can be useful
when loading statically-generated code into an address-space in a
non-standard fashion (i.e., through some means other than
\Func{dlopen}()). In this format, the details of a group of procedures
is described by a structure of type \Type{unw\_dyn\_table\_info}.
This structure contains the following members:
\begin{description}
\item[\Type{unw\_word\_t} \Var{name\_ptr}] The address of a
(human-readable) name of the procedure or 0 if no such name is
available. If non-zero, The string stored at this address must be
ASCII NUL terminated. For source languages that use name-mangling
(such as C++ or Java) the string stored at this address should be
the \emph{demangled} version of the name.
\item[\Type{unw\_word\_t} \Var{segbase}] The segment-base value
that needs to be added to the segment-relative values stored in the
unwind-info. The exact meaning of this value is
architecture-specific.
\item[\Type{unw\_word\_t} \Var{table\_len}] The length of the
unwind-info (\Var{table\_data}) counted in units of words
(\Type{unw\_word\_t}).
\item[\Type{unw\_word\_t} \Var{table\_data}] A pointer to the actual
data encoding the unwind-info. The exact format is
architecture-specific (see architecture-specific sections below).
\end{description}
\subsection{Remote table-info format}
The remote table-info format has the same basic purpose as the regular
table-info format. The only difference is that when \Prog{libunwind}
uses the unwind-info, it will keep the table data in the target
address-space (which may be remote). Consequently, the type of the
\Var{table\_data} member is \Type{unw\_word\_t} rather than a pointer.
This implies that \Prog{libunwind} will have to access the table-data
via the address-space's \Func{access\_mem}() call-back, rather than
through a direct memory reference.
From the point of view of a runtime-code generator, the remote
table-info format offers no advantage and it is expected that such
generators will describe their procedures either with the proc-info
format or the normal table-info format. The main reason that the
remote table-info format exists is to enable the
address-space-specific \Func{find\_proc\_info}() callback (see
\SeeAlso{unw\_create\_addr\_space}(3)) to return unwind tables whose
data remains in remote memory. This can speed up unwinding (e.g., for
a debugger) because it reduces the amount of data that needs to be
loaded from remote memory.
\section{Regions descriptors}
A region descriptor is a variable length structure that describes how
each instruction in the region affects the frame state. Of course,
most instructions in a region usualy do not change the frame state and
for those, nothing needs to be recorded in the region descriptor. A
region descriptor is a structure of type
\Type{unw\_dyn\_region\_info\_t} and has the following members:
\begin{description}
\item[\Type{unw\_dyn\_region\_info\_t~*}\Var{next}] A pointer to the
next region. If this is the last region, \Var{next} is \Const{NULL}.
\item[\Type{int32\_t} \Var{insn\_count}] The length of the region in
instructions. Each instruction is assumed to have a fixed size (see
architecture-specific sections for details). The value of
\Var{insn\_count} may be negative in the last region of a procedure
(i.e., it may be negative only if \Var{next} is \Const{NULL}). A
negative value indicates that the region covers the last \emph{N}
instructions of the procedure, where \emph{N} is the absolute value
of \Var{insn\_count}.
\item[\Type{uint32\_t} \Var{op\_count}] The (allocated) length of
the \Var{op\_count} array.
\item[\Type{unw\_dyn\_op\_t} \Var{op}] An array of dynamic unwind
directives. See Section ``Dynamic unwind directives'' for a
description of the directives.
\end{description}
A region descriptor with an \Var{insn\_count} of zero is an
\emph{empty region} and such regions are perfectly legal. In fact,
empty regions can be useful to establish a particular frame state
before the start of another region.
A single region list can be shared across multiple procedures provided
those procedures share a common prologue and epilogue (their bodies
may differ, of course). Normally, such procedures consist of a canned
prologue, the body, and a canned epilogue. This could be described by
two regions: one covering the prologue and one covering the epilogue.
Since the body length is variable, the latter region would need to
specify a negative value in \Var{insn\_count} such that
\Prog{libunwind} knows that the region covers the end of the procedure
(up to the address specified by \Var{end\_ip}).
The region descriptor is a variable length structure to make it
possible to allocate all the necessary memory with a single
memory-allocation request. To facilitate the allocation of a region
descriptors \Prog{libunwind} provides a helper routine with the
following synopsis:
\noindent
\Type{size\_t} \Func{\_U\_dyn\_region\_size}(\Type{int} \Var{op\_count});
This routine returns the number of bytes needed to hold a region
descriptor with space for \Var{op\_count} unwind directives. Note
that the length of the \Var{op} array does not have to match exactly
with the number of directives in a region. Instead, it is sufficient
if the \Var{op} array contains at least as many entries as there are
directives, since the end of the directives can always be indicated
with the \Const{UNW\_DYN\_STOP} directive.
\section{Dynamic unwind directives}
A dynamic unwind directive describes how the frame state changes
at a particular point within a region. The description is in
the form of a structure of type \Type{unw\_dyn\_op\_t}. This
structure has the following members:
\begin{description}
\item[\Type{int8\_t} \Var{tag}] The operation tag. Must be one
of the \Type{unw\_dyn\_operation\_t} values described below.
\item[\Type{int8\_t} \Var{qp}] The qualifying predicate that controls
whether or not this directive is active. This is useful for
predicated architecturs such as IA-64 or ARM, where the contents of
another (callee-saved) register determines whether or not an
instruction is executed (takes effect). If the directive is always
active, this member should be set to the manifest constant
\Const{\_U\_QP\_TRUE} (this constant is defined for all
architectures, predicated or not).
\item[\Type{int16\_t} \Var{reg}] The number of the register affected
by the instruction.
\item[\Type{int32\_t} \Var{when}] The region-relative number of
the instruction to which this directive applies. For example,
a value of 0 means that the effect described by this directive
has taken place once the first instruction in the region has
executed.
\item[\Type{unw\_word\_t} \Var{val}] The value to be applied by the
operation tag. The exact meaning of this value varies by tag. See
Section ``Operation tags'' below.
\end{description}
It is perfectly legitimate to specify multiple dynamic unwind
directives with the same \Var{when} value, if a particular instruction
has a complex effect on the frame state.
Empty regions by definition contain no actual instructions and as such
the directives are not tied to a particular instruction. By
convention, the \Var{when} member should be set to 0, however.
There is no need for the dynamic unwind directives to appear
in order of increasing \Var{when} values. If the directives happen to
be sorted in that order, it may result in slightly faster execution,
but a runtime code-generator should not go to extra lengths just to
ensure that the directives are sorted.
IMPLEMENTATION NOTE: should \Prog{libunwind} implementations for
certain architectures prefer the list of unwind directives to be
sorted, it is recommended that such implementations first check
whether the list happens to be sorted already and, if not, sort the
directives explicitly before the first use. With this approach, the
overhead of explicit sorting is only paid when there is a real benefit
and if the runtime code-generator happens to generated sorted lists
naturally, the performance penalty is limited to a simple O(N) check.
\subsection{Operations tags}
The possible operation tags are defined by enumeration type
\Type{unw\_dyn\_operation\_t} which defines the following
values:
\begin{description}
\item[\Const{UNW\_DYN\_STOP}] Marks the end of the dynamic unwind
directive list. All remaining entries in the \Var{op} array of the
region-descriptor are ignored. This tag is guaranteed to have a
value of 0.
\item[\Const{UNW\_DYN\_SAVE\_REG}] Marks an instruction which saves
register \Var{reg} to register \Var{val}.
\item[\Const{UNW\_DYN\_SPILL\_FP\_REL}] Marks an instruction which
spills register \Var{reg} to a frame-pointer-relative location. The
frame-pointer-relative offset is given by the value stored in member
\Var{val}. See the architecture-specific sections for a description
of the stack frame layout.
\item[\Const{UNW\_DYN\_SPILL\_SP\_REL}] Marks an instruction which
spills register \Var{reg} to a stack-pointer-relative location. The
stack-pointer-relative offset is given by the value stored in member
\Var{val}. See the architecture-specific sections for a description
of the stack frame layout.
\item[\Const{UNW\_DYN\_ADD}] Marks an instruction which adds
the constant value \Var{val} to register \Var{reg}. To add subtract
a constant value, store the two's-complement of the value in
\Var{val}. The set of registers that can be specified for this tag
is described in the architecture-specific sections below.
\item[\Const{UNW\_DYN\_POP\_FRAMES}]
\item[\Const{UNW\_DYN\_LABEL\_STATE}]
\item[\Const{UNW\_DYN\_COPY\_STATE}]
\item[\Const{UNW\_DYN\_ALIAS}]
\end{description}
unw\_dyn\_op\_t
\_U\_dyn\_op\_save\_reg();
\_U\_dyn\_op\_spill\_fp\_rel();
\_U\_dyn\_op\_spill\_sp\_rel();
\_U\_dyn\_op\_add();
\_U\_dyn\_op\_pop\_frames();
\_U\_dyn\_op\_label\_state();
\_U\_dyn\_op\_copy\_state();
\_U\_dyn\_op\_alias();
\_U\_dyn\_op\_stop();
\section{IA-64 specifics}
- meaning of segbase member in table-info/table-remote-info format
- format of table\_data in table-info/table-remote-info format
- instruction size: each bundle is counted as 3 instructions, regardless
of template (MLX)
- describe stack-frame layout, especially with regards to sp-relative
and fp-relative addressing
- UNW\_DYN\_ADD can only add to ``sp'' (always a negative value); use
POP\_FRAMES otherwise
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{\_U\_dyn\_register(3)},
\SeeAlso{\_U\_dyn\_cancel(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

314
sdk/cpprt/linux/libunwind/doc/libunwind-ia64.man Normal file
View File

@ -0,0 +1,314 @@
'\" t
.\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "LIBUNWIND\-IA64" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
libunwind\-ia64
\-\- IA\-64\-specific support in libunwind
.PP
.SH INTRODUCTION
.PP
The IA\-64 version of libunwind
uses a platform\-string of
ia64
and, at least in theory, should be able to support all
operating systems adhering to the processor\-specific ABI defined for
the Itanium Processor Family. This includes both little\-endian Linux
and big\-endian HP\-UX. Furthermore, to make it possible for a single
library to unwind both 32\- and 64\-bit targets, the type
unw_word_t
is always defined to be 64 bits wide (independent
of the natural word\-size of the host). Having said that, the current
implementation has been tested only with IA\-64 Linux.
.PP
When targeting IA\-64, the libunwind
header file defines the
macro UNW_TARGET_IA64
as 1 and the macro UNW_TARGET
as ``ia64\&'' (without the quotation marks). The former makes it
possible for platform\-dependent unwind code to use
conditional\-compilation to select an appropriate implementation. The
latter is useful for stringification purposes and to construct
target\-platform\-specific symbols.
.PP
One special feature of IA\-64 is the use of NaT bits to support
speculative execution. Often, NaT bits are thought of as the ``65\-th
bit\&'' of a general register. However, to make everything fit into
64\-bit wide unw_word_t
values, libunwind
treats the
NaT\-bits like separate boolean registers, whose 64\-bit value is either
TRUE (non\-zero) or FALSE (zero).
.PP
.SH MACHINE\-STATE
.PP
The machine\-state (set of registers) that is accessible through
libunwind
depends on the type of stack frame that a cursor
points to. For normal frames, all ``preserved\&'' (callee\-saved)
registers are accessible. For signal\-trampoline frames, all registers
(including ``scratch\&'' (caller\-saved) registers) are accessible. Most
applications do not have to worry a\-priori about which registers are
accessible when. In case of doubt, it is always safe to \fItry\fP
to
access a register (via unw_get_reg()
or
unw_get_fpreg())
and if the register isn\&'t accessible, the
call will fail with a return\-value of \-UNW_EBADREG\&.
.PP
As a special exception to the above general rule, scratch registers
r15\-r18
are always accessible, even in normal
frames. This makes it possible to pass arguments, e.g., to exception
handlers.
.PP
For a detailed description of the IA\-64 register usage convention,
please see the ``Itanium Software Conventions and Runtime Architecture
Guide\&'', available at:
.ce 100
\fBhttp://www.intel.com/design/itanium/downloads/245358.htm\fP
.ce 0
.PP
.SH REGISTER NAMES
.PP
The IA\-64\-version of libunwind
defines three kinds of register
name macros: frame\-register macros, normal register macros, and
convenience macros. Below, we describe each kind in turn:
.PP
.SS FRAME\-REGISTER MACROS
.PP
Frame\-registers are special (pseudo) registers because they always
have a valid value, even though sometimes they do not get saved
explicitly (e.g., if a memory stack frame is 16 bytes in size, the
previous stack\-pointer value can be calculated simply as
sp+16,
so there is no need to save the stack\-pointer
explicitly). Moreover, the set of frame register values uniquely
identifies a stack frame. The IA\-64 architecture defines two stacks
(a memory and a register stack). Including the instruction\-pointer
(IP), this means there are three frame registers:
.TP
UNW_IA64_IP:
Contains the instruction pointer (IP, or
``program counter\&'') of the current stack frame. Given this value,
the remaining machine\-state corresponds to the register\-values that
were present in the CPU when it was just about to execute the
instruction pointed to by UNW_IA64_IP\&.
Bits 0 and 1 of
this frame\-register encode the slot number of the instruction.
\fBNote:\fP
Due to the way the call instruction works on IA\-64,
the slot number is usually zero, but can be non\-zero, e.g., in the
stack\-frame of a signal\-handler trampoline.
.TP
UNW_IA64_SP:
Contains the (memory) stack\-pointer
value (SP).
.TP
UNW_IA64_BSP:
Contains the register backing\-store
pointer (BSP). \fBNote:\fP
the value in this register is equal
to the contents of register ar.bsp
at the time the
instruction at UNW_IA64_IP
was about to begin execution.
.PP
.SS NORMAL REGISTER MACROS
.PP
The following normal register name macros are available:
.TP
UNW_IA64_GR:
The base\-index for general (integer)
registers. Add an index in the range from 0..127 to get a
particular general register. For example, to access r4,
the index UNW_IA64_GR+4
should be used.
Registers r0
and r1
(gp)
are read\-only,
and any attempt to write them will result in an error
(\-UNW_EREADONLYREG).
Even though r1
is
read\-only, libunwind
will automatically adjust its value if
the instruction\-pointer (UNW_IA64_IP)
is modified. For
example, if UNW_IA64_IP
is set to a value inside a
function func(),
then reading
UNW_IA64_GR+1
will return the global\-pointer
value for this function.
.TP
UNW_IA64_NAT:
The base\-index for the NaT bits of the
general (integer) registers. A non\-zero value in these registers
corresponds to a set NaT\-bit. Add an index in the range from 0..127
to get a particular NaT\-bit register. For example, to access the
NaT bit of r4,
the index UNW_IA64_NAT+4
should be used.
.TP
UNW_IA64_FR:
The base\-index for floating\-point
registers. Add an index in the range from 0..127 to get a
particular floating\-point register. For example, to access
f2,
the index UNW_IA64_FR+2
should be
used. Registers f0
and f1
are read\-only, and any
attempt to write to indices UNW_IA64_FR+0
or
UNW_IA64_FR+1
will result in an error
(\-UNW_EREADONLYREG).
.TP
UNW_IA64_AR:
The base\-index for application
registers. Add an index in the range from 0..127 to get a
particular application register. For example, to access
ar40,
the index UNW_IA64_AR+40
should be
used. The IA\-64 architecture defines several application registers
as ``reserved for future use\&''\&. Attempting to access such registers
results in an error (\-UNW_EBADREG).
.TP
UNW_IA64_BR:
The base\-index for branch registers.
Add an index in the range from 0..7 to get a particular branch
register. For example, to access b6,
the index
UNW_IA64_BR+6
should be used.
.TP
UNW_IA64_PR:
Contains the set of predicate registers.
This 64\-bit wide register contains registers p0
through
p63
in the ``broad\-side\&'' format. Just like with the
``move predicates\&'' instruction, the registers are mapped as if
CFM.rrb.pr
were set to 0. Thus, in general the value of
predicate register pN
with N>=16 can be found
in bit 16 + ((N\-16)+CFM.rrb.pr) % 48\&.
.TP
UNW_IA64_CFM:
Contains the current\-frame\-mask
register.
.PP
.SS CONVENIENCE MACROS
.PP
Convenience macros are simply aliases for certain frequently used
registers:
.TP
UNW_IA64_GP:
Alias for UNW_IA64_GR+1,
the global\-pointer register.
.TP
UNW_IA64_TP:
Alias for UNW_IA64_GR+13,
the thread\-pointer register.
.TP
UNW_IA64_AR_RSC:
Alias for UNW_IA64_GR+16,
the register\-stack configuration register.
.TP
UNW_IA64_AR_BSP:
Alias for
UNW_IA64_GR+17\&.
This register index accesses the
value of register ar.bsp
as of the time it was last saved
explicitly. This is rarely what you want. Normally, you\&'ll want to
use UNW_IA64_BSP
instead.
.TP
UNW_IA64_AR_BSPSTORE:
Alias for UNW_IA64_GR+18,
the register\-backing store write pointer.
.TP
UNW_IA64_AR_RNAT:
Alias for UNW_IA64_GR+19,
the register\-backing store NaT\-collection register.
.TP
UNW_IA64_AR_CCV:
Alias for UNW_IA64_GR+32,
the compare\-and\-swap value register.
.TP
UNW_IA64_AR_CSD:
Alias for UNW_IA64_GR+25,
the compare\-and\-swap\-data register (used by 16\-byte atomic operations).
.TP
UNW_IA64_AR_UNAT:
Alias for UNW_IA64_GR+36,
the user NaT\-collection register.
.TP
UNW_IA64_AR_FPSR:
Alias for UNW_IA64_GR+40,
the floating\-point status (and control) register.
.TP
UNW_IA64_AR_PFS:
Alias for UNW_IA64_GR+64,
the previous frame\-state register.
.TP
UNW_IA64_AR_LC:
Alias for UNW_IA64_GR+65
the loop\-count register.
.TP
UNW_IA64_AR_EC:
Alias for UNW_IA64_GR+66,
the epilogue\-count register.
.PP
.SH THE UNWIND\-CONTEXT TYPE
.PP
On IA\-64, unw_context_t
is simply an alias for
ucontext_t
(as defined by the Single UNIX Spec). This implies
that it is possible to initialize a value of this type not just with
unw_getcontext(),
but also with getcontext(),
for
example. However, since this is an IA\-64\-specific extension to
libunwind,
portable code should not rely on this equivalence.
.PP
.SH SEE ALSO
.PP
libunwind(3)
.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.

216
sdk/cpprt/linux/libunwind/doc/libunwind-ia64.tex Normal file
View File

@ -0,0 +1,216 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{libunwind-ia64}{David Mosberger-Tang}{Programming Library}{IA-64-specific support in libunwind}libunwind-ia64 -- IA-64-specific support in libunwind
\end{Name}
\section{Introduction}
The IA-64 version of \Prog{libunwind} uses a platform-string of
\texttt{ia64} and, at least in theory, should be able to support all
operating systems adhering to the processor-specific ABI defined for
the Itanium Processor Family. This includes both little-endian Linux
and big-endian HP-UX. Furthermore, to make it possible for a single
library to unwind both 32- and 64-bit targets, the type
\Type{unw\_word\_t} is always defined to be 64 bits wide (independent
of the natural word-size of the host). Having said that, the current
implementation has been tested only with IA-64 Linux.
When targeting IA-64, the \Prog{libunwind} header file defines the
macro \Const{UNW\_TARGET\_IA64} as 1 and the macro \Const{UNW\_TARGET}
as ``ia64'' (without the quotation marks). The former makes it
possible for platform-dependent unwind code to use
conditional-compilation to select an appropriate implementation. The
latter is useful for stringification purposes and to construct
target-platform-specific symbols.
One special feature of IA-64 is the use of NaT bits to support
speculative execution. Often, NaT bits are thought of as the ``65-th
bit'' of a general register. However, to make everything fit into
64-bit wide \Type{unw\_word\_t} values, \Prog{libunwind} treats the
NaT-bits like separate boolean registers, whose 64-bit value is either
TRUE (non-zero) or FALSE (zero).
\section{Machine-State}
The machine-state (set of registers) that is accessible through
\Prog{libunwind} depends on the type of stack frame that a cursor
points to. For normal frames, all ``preserved'' (callee-saved)
registers are accessible. For signal-trampoline frames, all registers
(including ``scratch'' (caller-saved) registers) are accessible. Most
applications do not have to worry a-priori about which registers are
accessible when. In case of doubt, it is always safe to \emph{try} to
access a register (via \Func{unw\_get\_reg}() or
\Func{unw\_get\_fpreg}()) and if the register isn't accessible, the
call will fail with a return-value of \texttt{-}\Const{UNW\_EBADREG}.
As a special exception to the above general rule, scratch registers
\texttt{r15}-\texttt{r18} are always accessible, even in normal
frames. This makes it possible to pass arguments, e.g., to exception
handlers.
For a detailed description of the IA-64 register usage convention,
please see the ``Itanium Software Conventions and Runtime Architecture
Guide'', available at:
\begin{center}
\URL{http://www.intel.com/design/itanium/downloads/245358.htm}
\end{center}
\section{Register Names}
The IA-64-version of \Prog{libunwind} defines three kinds of register
name macros: frame-register macros, normal register macros, and
convenience macros. Below, we describe each kind in turn:
\subsection{Frame-register Macros}
Frame-registers are special (pseudo) registers because they always
have a valid value, even though sometimes they do not get saved
explicitly (e.g., if a memory stack frame is 16 bytes in size, the
previous stack-pointer value can be calculated simply as
\texttt{sp+16}, so there is no need to save the stack-pointer
explicitly). Moreover, the set of frame register values uniquely
identifies a stack frame. The IA-64 architecture defines two stacks
(a memory and a register stack). Including the instruction-pointer
(IP), this means there are three frame registers:
\begin{Description}
\item[\Const{UNW\_IA64\_IP}:] Contains the instruction pointer (IP, or
``program counter'') of the current stack frame. Given this value,
the remaining machine-state corresponds to the register-values that
were present in the CPU when it was just about to execute the
instruction pointed to by \Const{UNW\_IA64\_IP}. Bits 0 and 1 of
this frame-register encode the slot number of the instruction.
\textbf{Note:} Due to the way the call instruction works on IA-64,
the slot number is usually zero, but can be non-zero, e.g., in the
stack-frame of a signal-handler trampoline.
\item[\Const{UNW\_IA64\_SP}:] Contains the (memory) stack-pointer
value (SP).
\item[\Const{UNW\_IA64\_BSP}:] Contains the register backing-store
pointer (BSP). \textbf{Note:} the value in this register is equal
to the contents of register \texttt{ar.bsp} at the time the
instruction at \Const{UNW\_IA64\_IP} was about to begin execution.
\end{Description}
\subsection{Normal Register Macros}
The following normal register name macros are available:
\begin{Description}
\item[\Const{UNW\_IA64\_GR}:] The base-index for general (integer)
registers. Add an index in the range from 0..127 to get a
particular general register. For example, to access \texttt{r4},
the index \Const{UNW\_IA64\_GR}\texttt{+4} should be used.
Registers \texttt{r0} and \texttt{r1} (\texttt{gp}) are read-only,
and any attempt to write them will result in an error
(\texttt{-}\Const{UNW\_EREADONLYREG}). Even though \texttt{r1} is
read-only, \Prog{libunwind} will automatically adjust its value if
the instruction-pointer (\Const{UNW\_IA64\_IP}) is modified. For
example, if \Const{UNW\_IA64\_IP} is set to a value inside a
function \Func{func}(), then reading
\Const{UNW\_IA64\_GR}\texttt{+1} will return the global-pointer
value for this function.
\item[\Const{UNW\_IA64\_NAT}:] The base-index for the NaT bits of the
general (integer) registers. A non-zero value in these registers
corresponds to a set NaT-bit. Add an index in the range from 0..127
to get a particular NaT-bit register. For example, to access the
NaT bit of \texttt{r4}, the index \Const{UNW\_IA64\_NAT}\texttt{+4}
should be used.
\item[\Const{UNW\_IA64\_FR}:] The base-index for floating-point
registers. Add an index in the range from 0..127 to get a
particular floating-point register. For example, to access
\texttt{f2}, the index \Const{UNW\_IA64\_FR}\texttt{+2} should be
used. Registers \texttt{f0} and \texttt{f1} are read-only, and any
attempt to write to indices \Const{UNW\_IA64\_FR}\texttt{+0} or
\Const{UNW\_IA64\_FR}\texttt{+1} will result in an error
(\texttt{-}\Const{UNW\_EREADONLYREG}).
\item[\Const{UNW\_IA64\_AR}:] The base-index for application
registers. Add an index in the range from 0..127 to get a
particular application register. For example, to access
\texttt{ar40}, the index \Const{UNW\_IA64\_AR}\texttt{+40} should be
used. The IA-64 architecture defines several application registers
as ``reserved for future use''. Attempting to access such registers
results in an error (\texttt{-}\Const{UNW\_EBADREG}).
\item[\Const{UNW\_IA64\_BR}:] The base-index for branch registers.
Add an index in the range from 0..7 to get a particular branch
register. For example, to access \texttt{b6}, the index
\Const{UNW\_IA64\_BR}\texttt{+6} should be used.
\item[\Const{UNW\_IA64\_PR}:] Contains the set of predicate registers.
This 64-bit wide register contains registers \texttt{p0} through
\texttt{p63} in the ``broad-side'' format. Just like with the
``move predicates'' instruction, the registers are mapped as if
\texttt{CFM.rrb.pr} were set to 0. Thus, in general the value of
predicate register \texttt{p}$N$ with $N$>=16 can be found
in bit \texttt{16 + (($N$-16)+CFM.rrb.pr) \% 48}.
\item[\Const{UNW\_IA64\_CFM}:] Contains the current-frame-mask
register.
\end{Description}
\subsection{Convenience Macros}
Convenience macros are simply aliases for certain frequently used
registers:
\begin{Description}
\item[\Const{UNW\_IA64\_GP}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+1},
the global-pointer register.
\item[\Const{UNW\_IA64\_TP}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+13},
the thread-pointer register.
\item[\Const{UNW\_IA64\_AR\_RSC}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+16},
the register-stack configuration register.
\item[\Const{UNW\_IA64\_AR\_BSP}:] Alias for
\Const{UNW\_IA64\_GR}\texttt{+17}. This register index accesses the
value of register \texttt{ar.bsp} as of the time it was last saved
explicitly. This is rarely what you want. Normally, you'll want to
use \Const{UNW\_IA64\_BSP} instead.
\item[\Const{UNW\_IA64\_AR\_BSPSTORE}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+18},
the register-backing store write pointer.
\item[\Const{UNW\_IA64\_AR\_RNAT}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+19},
the register-backing store NaT-collection register.
\item[\Const{UNW\_IA64\_AR\_CCV}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+32},
the compare-and-swap value register.
\item[\Const{UNW\_IA64\_AR\_CSD}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+25},
the compare-and-swap-data register (used by 16-byte atomic operations).
\item[\Const{UNW\_IA64\_AR\_UNAT}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+36},
the user NaT-collection register.
\item[\Const{UNW\_IA64\_AR\_FPSR}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+40},
the floating-point status (and control) register.
\item[\Const{UNW\_IA64\_AR\_PFS}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+64},
the previous frame-state register.
\item[\Const{UNW\_IA64\_AR\_LC}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+65}
the loop-count register.
\item[\Const{UNW\_IA64\_AR\_EC}:] Alias for \Const{UNW\_IA64\_GR}\texttt{+66},
the epilogue-count register.
\end{Description}
\section{The Unwind-Context Type}
On IA-64, \Type{unw\_context\_t} is simply an alias for
\Type{ucontext\_t} (as defined by the Single UNIX Spec). This implies
that it is possible to initialize a value of this type not just with
\Func{unw\_getcontext}(), but also with \Func{getcontext}(), for
example. However, since this is an IA-64-specific extension to
\Prog{libunwind}, portable code should not rely on this equivalence.
\section{See Also}
\SeeAlso{libunwind(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

220
sdk/cpprt/linux/libunwind/doc/libunwind-ptrace.man Normal file
View File

@ -0,0 +1,220 @@
'\" t
.\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "LIBUNWIND\-PTRACE" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
libunwind\-ptrace
\-\- ptrace() support in libunwind
.PP
.SH SYNOPSIS
.PP
#include <libunwind\-ptrace.h>
.br
.PP
unw_accessors_t
_UPT_accessors;
.br
.PP
void *_UPT_create(pid_t);
.br
void
_UPT_destroy(void *);
.br
.PP
int
_UPT_find_proc_info(unw_addr_space_t,
unw_word_t,
unw_proc_info_t *,
int,
void *);
.br
void
_UPT_put_unwind_info(unw_addr_space_t,
unw_proc_info_t *,
void *);
.br
int
_UPT_get_dyn_info_list_addr(unw_addr_space_t,
unw_word_t *,
void *);
.br
int
_UPT_access_mem(unw_addr_space_t,
unw_word_t,
unw_word_t *,
int,
void *);
.br
int
_UPT_access_reg(unw_addr_space_t,
unw_regnum_t,
unw_word_t *,
int,
void *);
.br
int
_UPT_access_fpreg(unw_addr_space_t,
unw_regnum_t,
unw_fpreg_t *,
int,
void *);
.br
int
_UPT_get_proc_name(unw_addr_space_t,
unw_word_t,
char *,
size_t,
unw_word_t *,
void *);
.br
int
_UPT_resume(unw_addr_space_t,
unw_cursor_t *,
void *);
.br
.PP
.SH DESCRIPTION
.PP
The ptrace(2)
system\-call makes it possible for a process to
gain access to the machine\-state and virtual memory of \fIanother\fP
process. With the right set of call\-back routines, it is therefore
possible to hook up libunwind
to another process via
ptrace(2).
While it\&'s not very difficult to do so directly,
libunwind
further facilitates this task by providing
ready\-to\-use callbacks for this purpose. The routines and variables
implementing this facility use a name\-prefix of _UPT,
which is
stands for ``unwind\-via\-ptrace\&''\&.
.PP
An application that wants to use the _UPT\-facility
first needs
to create a new libunwind
address\-space that represents the
target process. This is done by calling
unw_create_addr_space().
In many cases, the application
will simply want to pass the address of _UPT_accessors
as the
first argument to this routine. Doing so will ensure that
libunwind
will be able to properly unwind the target process.
However, in special circumstances, an application may prefer to use
only portions of the _UPT\-facility.
For this reason, the
individual callback routines (_UPT_find_proc_info(),
_UPT_put_unwind_info(),
etc.) are also available for direct
use. Of course, the addresses of these routines could also be picked
up from _UPT_accessors,
but doing so would prevent static
initialization. Also, when using _UPT_accessors,
\fIall\fP
the callback routines will be linked into the application, even if
they are never actually called.
.PP
Next, the application can turn on ptrace\-mode on the target process,
either by forking a new process, invoking PTRACE_TRACEME,
and
then starting the target program (via execve(2)),
or by
directly attaching to an already running process (via
PTRACE_ATTACH).
Either way, once the process\-ID (pid) of the
target process is known, a _UPT\-info\-structure
can be created
by calling _UPT_create(),
passing the pid of the target process
as the only argument. The returned void\-pointer then needs to be
passed as the ``argument\&'' pointer (third argument) to
unw_init_remote().
.PP
The _UPT_resume()
routine can be used to resume execution of
the target process. It simply invokes ptrace(2)
with a command
value of PTRACE_CONT\&.
.PP
When the application is done using libunwind
on the target
process, _UPT_destroy()
needs to be called, passing it the
void\-pointer that was returned by the corresponding call to
_UPT_create().
This ensures that all memory and other
resources are freed up.
.PP
.SH AVAILABILITY
.PP
Since ptrace(2)
works within a single machine only, the
_UPT\-facility
by definition is not available in
libunwind\-versions
configured for cross\-unwinding.
.PP
.SH THREAD SAFETY
.PP
The _UPT\-facility
assumes that a single _UPT\-info
structure is never shared between threads. Because of this, no
explicit locking is used. As long as only one thread uses
a _UPT\-info
structure at any given time, this facility
is thread\-safe.
.PP
.SH RETURN VALUE
.PP
_UPT_create()
may return a NULL
pointer if it fails
to create the _UPT\-info\-structure
for any reason. For the
current implementation, the only reason this call may fail is when the
system is out of memory.
.PP
.SH FILES
.PP
.TP
libunwind\-ptrace.h
Headerfile to include when using the
interface defined by this library.
.TP
\fB\-l\fPunwind\-ptrace \fB\-l\fPunwind\-generic
Linker\-switches to add when building a program that uses the
functions defined by this library.
.PP
.SH SEE ALSO
.PP
execve(2),
libunwind(3),
ptrace(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.

134
sdk/cpprt/linux/libunwind/doc/libunwind-ptrace.tex Normal file
View File

@ -0,0 +1,134 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{libunwind-ptrace}{David Mosberger-Tang}{Programming Library}{ptrace() support in libunwind}libunwind-ptrace -- ptrace() support in libunwind
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind-ptrace.h$>$}\\
\noindent
\Type{unw\_accessors\_t} \Var{\_UPT\_accessors};\\
\Type{void~*}\Func{\_UPT\_create}(\Type{pid\_t});\\
\noindent
\Type{void} \Func{\_UPT\_destroy}(\Type{void~*});\\
\noindent
\Type{int} \Func{\_UPT\_find\_proc\_info}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{unw\_proc\_info\_t~*}, \Type{int}, \Type{void~*});\\
\noindent
\Type{void} \Func{\_UPT\_put\_unwind\_info}(\Type{unw\_addr\_space\_t}, \Type{unw\_proc\_info\_t~*}, \Type{void~*});\\
\noindent
\Type{int} \Func{\_UPT\_get\_dyn\_info\_list\_addr}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t~*}, \Type{void~*});\\
\noindent
\Type{int} \Func{\_UPT\_access\_mem}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{unw\_word\_t~*}, \Type{int}, \Type{void~*});\\
\noindent
\Type{int} \Func{\_UPT\_access\_reg}(\Type{unw\_addr\_space\_t}, \Type{unw\_regnum\_t}, \Type{unw\_word\_t~*}, \Type{int}, \Type{void~*});\\
\noindent
\Type{int} \Func{\_UPT\_access\_fpreg}(\Type{unw\_addr\_space\_t}, \Type{unw\_regnum\_t}, \Type{unw\_fpreg\_t~*}, \Type{int}, \Type{void~*});\\
\noindent
\Type{int} \Func{\_UPT\_get\_proc\_name}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{char~*}, \Type{size\_t}, \Type{unw\_word\_t~*}, \Type{void~*});\\
\noindent
\Type{int} \Func{\_UPT\_resume}(\Type{unw\_addr\_space\_t}, \Type{unw\_cursor\_t~*}, \Type{void~*});\\
\section{Description}
The \Func{ptrace}(2) system-call makes it possible for a process to
gain access to the machine-state and virtual memory of \emph{another}
process. With the right set of call-back routines, it is therefore
possible to hook up \Prog{libunwind} to another process via
\Func{ptrace}(2). While it's not very difficult to do so directly,
\Prog{libunwind} further facilitates this task by providing
ready-to-use callbacks for this purpose. The routines and variables
implementing this facility use a name-prefix of \Func{\_UPT}, which is
stands for ``unwind-via-ptrace''.
An application that wants to use the \Func{\_UPT}-facility first needs
to create a new \Prog{libunwind} address-space that represents the
target process. This is done by calling
\Func{unw\_create\_addr\_space}(). In many cases, the application
will simply want to pass the address of \Var{\_UPT\_accessors} as the
first argument to this routine. Doing so will ensure that
\Prog{libunwind} will be able to properly unwind the target process.
However, in special circumstances, an application may prefer to use
only portions of the \Prog{\_UPT}-facility. For this reason, the
individual callback routines (\Func{\_UPT\_find\_proc\_info}(),
\Func{\_UPT\_put\_unwind\_info}(), etc.) are also available for direct
use. Of course, the addresses of these routines could also be picked
up from \Var{\_UPT\_accessors}, but doing so would prevent static
initialization. Also, when using \Var{\_UPT\_accessors}, \emph{all}
the callback routines will be linked into the application, even if
they are never actually called.
Next, the application can turn on ptrace-mode on the target process,
either by forking a new process, invoking \Const{PTRACE\_TRACEME}, and
then starting the target program (via \Func{execve}(2)), or by
directly attaching to an already running process (via
\Const{PTRACE\_ATTACH}). Either way, once the process-ID (pid) of the
target process is known, a \Prog{\_UPT}-info-structure can be created
by calling \Func{\_UPT\_create}(), passing the pid of the target process
as the only argument. The returned void-pointer then needs to be
passed as the ``argument'' pointer (third argument) to
\Func{unw\_init\_remote}().
The \Func{\_UPT\_resume}() routine can be used to resume execution of
the target process. It simply invokes \Func{ptrace}(2) with a command
value of \Const{PTRACE\_CONT}.
When the application is done using \Prog{libunwind} on the target
process, \Func{\_UPT\_destroy}() needs to be called, passing it the
void-pointer that was returned by the corresponding call to
\Func{\_UPT\_create}(). This ensures that all memory and other
resources are freed up.
\section{Availability}
Since \Func{ptrace}(2) works within a single machine only, the
\Prog{\_UPT}-facility by definition is not available in
\Prog{libunwind}-versions configured for cross-unwinding.
\section{Thread Safety}
The \Prog{\_UPT}-facility assumes that a single \Prog{\_UPT}-info
structure is never shared between threads. Because of this, no
explicit locking is used. As long as only one thread uses
a \Prog{\_UPT}-info structure at any given time, this facility
is thread-safe.
\section{Return Value}
\Func{\_UPT\_create}() may return a \Const{NULL} pointer if it fails
to create the \Prog{\_UPT}-info-structure for any reason. For the
current implementation, the only reason this call may fail is when the
system is out of memory.
\section{Files}
\begin{Description}
\item[\File{libunwind-ptrace.h}] Headerfile to include when using the
interface defined by this library.
\item[\Opt{-l}\File{unwind-ptrace} \Opt{-l}\File{unwind-generic}]
Linker-switches to add when building a program that uses the
functions defined by this library.
\end{Description}
\section{See Also}
execve(2),
\SeeAlso{libunwind(3)},
ptrace(2)
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

132
sdk/cpprt/linux/libunwind/doc/libunwind-setjmp.man Normal file
View File

@ -0,0 +1,132 @@
'\" t
.\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "LIBUNWIND\-SETJMP" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
libunwind\-setjmp
\-\- libunwind\-based non\-local gotos
.PP
.SH SYNOPSIS
.PP
#include <setjmp.h>
.br
.PP
int
setjmp(jmp_buf env);
.br
void
longjmp(jmp_buf env,
int val);
.br
int
_setjmp(jmp_buf env);
.br
void
_longjmp(jmp_buf env,
int val);
.br
int
setjmp(sigjmp_buf env,
int savemask);
.br
void
siglongjmp(sigjmp_buf env,
int val);
.br
.PP
.SH DESCRIPTION
.PP
The unwind\-setjmp
library offers a libunwind\-based
implementation of non\-local gotos. This implementation is intended to
be a drop\-in replacement for the normal, system\-provided routines of
the same name. The main advantage of using the unwind\-setjmp
library is that setting up a non\-local goto via one of the
setjmp()
routines is very fast. Typically, just 2 or 3 words
need to be saved in the jump\-buffer (plus one call to
sigprocmask(2),
in the case of sigsetjmp).
On the
other hand, executing a non\-local goto by calling one of the
longjmp()
routines tends to be much slower than with the
system\-provided routines. In fact, the time spent on a
longjmp()
will be proportional to the number of call frames
that exist between the points where setjmp()
and
longjmp()
were called. For this reason, the
unwind\-setjmp
library is beneficial primarily in applications
that frequently call setjmp()
but only rarely call
longjmp().
.PP
.SH CAVEATS
.PP
.TP
.B *
The correct operation of this library depends on the presence of
correct unwind information. On newer platforms, this is rarely an
issue. On older platforms, care needs to be taken to
ensure that each of the functions whose stack frames may have to be
unwound during a longjmp()
have correct unwind information
(on those platforms, there is usually a compiler\-switch, such as
\fB\-funwind\-tables\fP,
to request the generation of unwind
information).
.TP
.B *
The contents of jmp_buf and sigjmp_buf as setup
and used by these routines is completely different from the ones
used by the system\-provided routines. Thus, a jump\-buffer created
by the libunwind\-based setjmp()/_setjmp
may only be
used in a call to the libunwind\-based
longjmp()/_longjmp().
The analogous applies for
sigjmp_buf
with sigsetjmp()
and siglongjmp().
.PP
.SH FILES
.PP
.TP
\fB\-l\fPunwind\-setjmp
The library an application should
be linked against to ensure it uses the libunwind\-based non\-local
goto routines.
.PP
.SH SEE ALSO
.PP
libunwind(3),
setjmp(3), longjmp(3),
_setjmp(3), _longjmp(3),
sigsetjmp(3), siglongjmp(3)
.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.

87
sdk/cpprt/linux/libunwind/doc/libunwind-setjmp.tex Normal file
View File

@ -0,0 +1,87 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{libunwind-setjmp}{David Mosberger-Tang}{Programming Library}{libunwind-based non-local gotos}libunwind-setjmp -- libunwind-based non-local gotos
\end{Name}
\section{Synopsis}
\File{\#include $<$setjmp.h$>$}\\
\noindent
\Type{int} \Func{setjmp}(\Type{jmp\_buf}~\Var{env});\\
\Type{void} \Func{longjmp}(\Type{jmp\_buf}~\Var{env}, \Type{int}~\Var{val});\\
\Type{int} \Func{\_setjmp}(\Type{jmp\_buf}~\Var{env});\\
\Type{void} \Func{\_longjmp}(\Type{jmp\_buf}~\Var{env}, \Type{int}~\Var{val});\\
\Type{int} \Func{setjmp}(\Type{sigjmp\_buf}~\Var{env}, \Type{int}~\Var{savemask});\\
\Type{void} \Func{siglongjmp}(\Type{sigjmp\_buf}~\Var{env}, \Type{int}~\Var{val});\\
\section{Description}
The \Prog{unwind-setjmp} library offers a \Prog{libunwind}-based
implementation of non-local gotos. This implementation is intended to
be a drop-in replacement for the normal, system-provided routines of
the same name. The main advantage of using the \Prog{unwind-setjmp}
library is that setting up a non-local goto via one of the
\Func{setjmp}() routines is very fast. Typically, just 2 or 3 words
need to be saved in the jump-buffer (plus one call to
\Func{sigprocmask}(2), in the case of \Func{sigsetjmp}). On the
other hand, executing a non-local goto by calling one of the
\Func{longjmp}() routines tends to be much slower than with the
system-provided routines. In fact, the time spent on a
\Func{longjmp}() will be proportional to the number of call frames
that exist between the points where \Func{setjmp}() and
\Func{longjmp}() were called. For this reason, the
\Prog{unwind-setjmp} library is beneficial primarily in applications
that frequently call \Func{setjmp}() but only rarely call
\Func{longjmp}().
\section{Caveats}
\begin{itemize}
\item The correct operation of this library depends on the presence of
correct unwind information. On newer platforms, this is rarely an
issue. On older platforms, care needs to be taken to
ensure that each of the functions whose stack frames may have to be
unwound during a \Func{longjmp}() have correct unwind information
(on those platforms, there is usually a compiler-switch, such as
\Opt{-funwind-tables}, to request the generation of unwind
information).
\item The contents of \Type{jmp\_buf} and \Type{sigjmp\_buf} as setup
and used by these routines is completely different from the ones
used by the system-provided routines. Thus, a jump-buffer created
by the libunwind-based \Func{setjmp}()/\Func{\_setjmp} may only be
used in a call to the libunwind-based
\Func{longjmp}()/\Func{\_longjmp}(). The analogous applies for
\Type{sigjmp\_buf} with \Func{sigsetjmp}() and \Func{siglongjmp}().
\end{itemize}
\section{Files}
\begin{Description}
\item[\Opt{-l}\File{unwind-setjmp}] The library an application should
be linked against to ensure it uses the libunwind-based non-local
goto routines.
\end{Description}
\section{See Also}
\SeeAlso{libunwind(3)},
setjmp(3), longjmp(3),
\_setjmp(3), \_longjmp(3),
sigsetjmp(3), siglongjmp(3)
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

500
sdk/cpprt/linux/libunwind/doc/libunwind.man Normal file
View File

@ -0,0 +1,500 @@
'\" t
.\" Manual page created with latex2man on Thu Aug 16 09:44:43 MDT 2007
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "LIBUNWIND" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
libunwind
\-\- a (mostly) platform\-independent unwind API
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_getcontext(unw_context_t *);
.br
int
unw_init_local(unw_cursor_t *,
unw_context_t *);
.br
int
unw_init_remote(unw_cursor_t *,
unw_addr_space_t,
void *);
.br
int
unw_step(unw_cursor_t *);
.br
int
unw_get_reg(unw_cursor_t *,
unw_regnum_t,
unw_word_t *);
.br
int
unw_get_fpreg(unw_cursor_t *,
unw_regnum_t,
unw_fpreg_t *);
.br
int
unw_set_reg(unw_cursor_t *,
unw_regnum_t,
unw_word_t);
.br
int
unw_set_fpreg(unw_cursor_t *,
unw_regnum_t,
unw_fpreg_t);
.br
int
unw_resume(unw_cursor_t *);
.br
.PP
unw_addr_space_t
unw_local_addr_space;
.br
unw_addr_space_t
unw_create_addr_space(unw_accessors_t,
int);
.br
void
unw_destroy_addr_space(unw_addr_space_t);
.br
unw_accessors_t
unw_get_accessors(unw_addr_space_t);
.br
void
unw_flush_cache(unw_addr_space_t,
unw_word_t,
unw_word_t);
.br
int
unw_set_caching_policy(unw_addr_space_t,
unw_caching_policy_t);
.br
.PP
const char *unw_regname(unw_regnum_t);
.br
int
unw_get_proc_info(unw_cursor_t *,
unw_proc_info_t *);
.br
int
unw_get_save_loc(unw_cursor_t *,
int,
unw_save_loc_t *);
.br
int
unw_is_fpreg(unw_regnum_t);
.br
int
unw_is_signal_frame(unw_cursor_t *);
.br
int
unw_get_proc_name(unw_cursor_t *,
char *,
size_t,
unw_word_t *);
.br
.PP
void
_U_dyn_register(unw_dyn_info_t *);
.br
void
_U_dyn_cancel(unw_dyn_info_t *);
.br
.PP
.SH LOCAL UNWINDING
.PP
Libunwind
is very easy to use when unwinding a stack from
within a running program. This is called \fIlocal\fP
unwinding. Say
you want to unwind the stack while executing in some function
F().
In this function, you would call unw_getcontext()
to get a snapshot of the CPU registers (machine\-state). Then you
initialize an \fIunwind cursor\fP
based on this snapshot. This is
done with a call to unw_init_local().
The cursor now points
to the current frame, that is, the stack frame that corresponds to the
current activation of function F().
The unwind cursor can then
be moved ``up\&'' (towards earlier stack frames) by calling
unw_step().
By repeatedly calling this routine, you can
uncover the entire call\-chain that led to the activation of function
F().
A positive return value from unw_step()
indicates
that there are more frames in the chain, zero indicates that the end
of the chain has been reached, and any negative value indicates that
some sort of error has occurred.
.PP
While it is not possible to directly move the unwind cursor in the
``down\&'' direction (towards newer stack frames), this effect can be
achieved by making copies of an unwind cursor. For example, a program
that sometimes has to move ``down\&'' by one stack frame could maintain
two cursor variables: ``curr\&''
and ``prev\&''\&.
The former
would be used as the current cursor and prev
would be maintained
as the ``previous frame\&'' cursor by copying the contents of curr
to prev
right before calling unw_step().
With this
approach, the program could move one step ``down\&'' simply by copying
back prev
to curr
whenever that is necessary. In the most
extreme case, a program could maintain a separate cursor for each call
frame and that way it could move up and down the callframe\-chain at
will.
.PP
Given an unwind cursor, it is possible to read and write the CPU
registers that were preserved for the current stack frame (as
identified by the cursor). Libunwind
provides several routines
for this purpose: unw_get_reg()
reads an integer (general)
register, unw_get_fpreg()
reads a floating\-point register,
unw_set_reg()
writes an integer register, and
unw_set_fpreg()
writes a floating\-point register. Note that,
by definition, only the \fIpreserved\fP
machine state can be accessed
during an unwind operation. Normally, this state consists of the
\fIcallee\-saved\fP
(``preserved\&'') registers. However, in some
special circumstances (e.g., in a signal handler trampoline), even the
\fIcaller\-saved\fP
(``scratch\&'') registers are preserved in the stack
frame and, in those cases, libunwind
will grant access to them
as well. The exact set of registers that can be accessed via the
cursor depends, of course, on the platform. However, there are two
registers that can be read on all platforms: the instruction pointer
(IP), sometimes also known as the ``program counter\&'', and the stack
pointer (SP). In libunwind,
these registers are identified by
the macros UNW_REG_IP
and UNW_REG_SP,
respectively.
.PP
Besides just moving the unwind cursor and reading/writing saved
registers, libunwind
also provides the ability to resume
execution at an arbitrary stack frame. As you might guess, this is
useful for implementing non\-local gotos and the exception handling
needed by some high\-level languages such as Java. Resuming execution
with a particular stack frame simply requires calling
unw_resume()
and passing the cursor identifying the target
frame as the only argument.
.PP
Normally, libunwind
supports both local and remote unwinding
(the latter will be explained in the next section). However, if you
tell libunwind that your program only needs local unwinding, then a
special implementation can be selected which may run much faster than
the generic implementation which supports both kinds of unwinding. To
select this optimized version, simply define the macro
UNW_LOCAL_ONLY
before including the headerfile
<libunwind.h>\&.
It is perfectly OK for a single program to
employ both local\-only and generic unwinding. That is, whether or not
UNW_LOCAL_ONLY
is defined is a choice that each source\-file
(compilation\-unit) can make on its own. Independent of the setting(s)
of UNW_LOCAL_ONLY,
you\&'ll always link the same library into
the program (normally \fB\-l\fPunwind).
Furthermore, the
portion of libunwind
that manages unwind\-info for dynamically
generated code is not affected by the setting of
UNW_LOCAL_ONLY\&.
.PP
If we put all of the above together, here is how we could use
libunwind
to write a function ``show_backtrace()\&''
which prints a classic stack trace:
.PP
.Vb
#define UNW_LOCAL_ONLY
#include <libunwind.h>
void show_backtrace (void) {
unw_cursor_t cursor; unw_context_t uc;
unw_word_t ip, sp;
unw_getcontext(&uc);
unw_init_local(&cursor, &uc);
while (unw_step(&cursor) > 0) {
unw_get_reg(&cursor, UNW_REG_IP, &ip);
unw_get_reg(&cursor, UNW_REG_SP, &sp);
printf ("ip = %lx, sp = %lx\\n", (long) ip, (long) sp);
}
}
.Ve
.PP
.SH REMOTE UNWINDING
.PP
Libunwind
can also be used to unwind a stack in a ``remote\&''
process. Here, ``remote\&'' may mean another process on the same
machine or even a process on a completely different machine from the
one that is running libunwind\&.
Remote unwinding is typically
used by debuggers and instruction\-set simulators, for example.
.PP
Before you can unwind a remote process, you need to create a new
address\-space object for that process. This is achieved with the
unw_create_addr_space()
routine. The routine takes two
arguments: a pointer to a set of \fIaccessor\fP
routines and an
integer that specifies the byte\-order of the target process. The
accessor routines provide libunwind
with the means to
communicate with the remote process. In particular, there are
callbacks to read and write the process\&'s memory, its registers, and
to access unwind information which may be needed by libunwind\&.
.PP
With the address space created, unwinding can be initiated by a call
to unw_init_remote().
This routine is very similar to
unw_init_local(),
except that it takes an address\-space
object and an opaque pointer as arguments. The routine uses these
arguments to fetch the initial machine state. Libunwind
never
uses the opaque pointer on its own, but instead just passes it on to
the accessor (callback) routines. Typically, this pointer is used to
select, e.g., the thread within a process that is to be unwound.
.PP
Once a cursor has been initialized with unw_init_remote(),
unwinding works exactly like in the local case. That is, you can use
unw_step()
to move ``up\&'' in the call\-chain, read and write
registers, or resume execution at a particular stack frame by calling
unw_resume\&.
.PP
.SH CROSS\-PLATFORM AND MULTI\-PLATFORM UNWINDING
.PP
Libunwind
has been designed to enable unwinding across
platforms (architectures). Indeed, a single program can use
libunwind
to unwind an arbitrary number of target platforms,
all at the same time!
.PP
We call the machine that is running libunwind
the \fIhost\fP
and the machine that is running the process being unwound the
\fItarget\fP\&.
If the host and the target platform are the same, we
call it \fInative\fP
unwinding. If they differ, we call it
\fIcross\-platform\fP
unwinding.
.PP
The principle behind supporting native, cross\-platform, and
multi\-platform unwinding is very simple: for native unwinding, a
program includes <libunwind.h>
and uses the linker switch
\fB\-l\fPunwind\&.
For cross\-platform unwinding, a program
includes <libunwind\-PLAT\&.h>
and uses the linker
switch \fB\-l\fPunwind\-PLAT,
where PLAT
is the name
of the target platform (e.g., ia64
for IA\-64, hppa\-elf
for ELF\-based HP PA\-RISC, or x86
for 80386). Multi\-platform
unwinding works exactly like cross\-platform unwinding, the only
limitation is that a single source file (compilation unit) can include
at most one libunwind
header file. In other words, the
platform\-specific support for each supported target needs to be
isolated in separate source files\-\-\-a limitation that shouldn\&'t be an
issue in practice.
.PP
Note that, by definition, local unwinding is possible only for the
native case. Attempting to call, e.g., unw_local_init()
when
targeting a cross\-platform will result in a link\-time error
(unresolved references).
.PP
.SH THREAD\- AND SIGNAL\-SAFETY
.PP
All libunwind
routines are thread\-safe. What this means is
that multiple threads may use libunwind
simulatenously.
However, any given cursor may be accessed by only one thread at
any given time.
.PP
To ensure thread\-safety, some libunwind
routines may have to
use locking. Such routines \fImust not\fP
be called from signal
handlers (directly or indirectly) and are therefore \fInot\fP
signal\-safe. The manual page for each libunwind
routine
identifies whether or not it is signal\-safe, but as a general rule,
any routine that may be needed for \fIlocal\fP
unwinding is
signal\-safe (e.g., unw_step()
for local unwinding is
signal\-safe). For remote\-unwinding, \fInone\fP
of the
libunwind
routines are guaranteed to be signal\-safe.
.PP
.SH UNWINDING THROUGH DYNAMICALLY GENERATED CODE
.PP
Libunwind
provides the routines _U_dyn_register()
and
_U_dyn_cancel()
to register/cancel the information required to
unwind through code that has been generated at runtime (e.g., by a
just\-in\-time (JIT) compiler). It is important to register the
information for \fIall\fP
dynamically generated code because
otherwise, a debugger may not be able to function properly or
high\-level language exception handling may not work as expected.
.PP
The interface for registering and canceling dynamic unwind info has
been designed for maximum efficiency, so as to minimize the
performance impact on JIT\-compilers. In particular, both routines are
guaranteed to execute in ``constant time\&'' (O(1)) and the
data\-structure encapsulating the dynamic unwind info has been designed
to facilitate sharing, such that similar procedures can share much of
the underlying information.
.PP
For more information on the libunwind
support for dynamically
generated code, see libunwind\-dynamic(3)\&.
.PP
.SH CACHING OF UNWIND INFO
.PP
To speed up execution, libunwind
may aggressively cache the
information it needs to perform unwinding. If a process changes
during its lifetime, this creates a risk of libunwind
using
stale data. For example, this would happen if libunwind
were
to cache information about a shared library which later on gets
unloaded (e.g., via \fIdlclose\fP(3)).
.PP
To prevent the risk of using stale data, libunwind
provides two
facilities: first, it is possible to flush the cached information
associated with a specific address range in the target process (or the
entire address space, if desired). This functionality is provided by
unw_flush_cache().
The second facility is provided by
unw_set_caching_policy(),
which lets a program
select the exact caching policy in use for a given address\-space
object. In particular, by selecting the policy
UNW_CACHE_NONE,
it is possible to turn off caching
completely, therefore eliminating the risk of stale data alltogether
(at the cost of slower execution). By default, caching is enabled for
local unwinding only.
.PP
.SH FILES
.PP
.TP
libunwind.h
Headerfile to include for native (same
platform) unwinding.
.TP
libunwind\-PLAT\&.h
Headerfile to include when
the unwind target runs on platform PLAT\&.
For example, to unwind
an IA\-64 program, the header file libunwind\-ia64.h
should be
included.
.TP
\fB\-l\fPunwind
Linker\-switch to add when building a
program that does native (same platform) unwinding.
.TP
\fB\-l\fPunwind\-PLAT
Linker\-switch to add when
building a program that unwinds a program on platform PLAT\&.
For example, to (cross\-)unwind an IA\-64 program, the linker switch
\-lunwind\-ia64
should be added. Note: multiple such switches
may need to be specified for programs that can unwind programs on
multiple platforms.
.PP
.SH SEE ALSO
.PP
libunwind\-dynamic(3),
libunwind\-ia64(3),
libunwind\-ptrace(3),
libunwind\-setjmp(3),
unw_create_addr_space(3),
unw_destroy_addr_space(3),
unw_flush_cache(3),
unw_get_accessors(3),
unw_get_fpreg(3),
unw_get_proc_info(3),
unw_get_proc_name(3),
unw_get_reg(3),
unw_getcontext(3),
unw_init_local(3),
unw_init_remote(3),
unw_is_fpreg(3),
unw_is_signal_frame(3),
unw_regname(3),
unw_resume(3),
unw_set_caching_policy(3),
unw_set_fpreg(3),
unw_set_reg(3),
unw_step(3),
unw_strerror(3),
_U_dyn_register(3),
_U_dyn_cancel(3)
.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.

355
sdk/cpprt/linux/libunwind/doc/libunwind.tex Normal file
View File

@ -0,0 +1,355 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{libunwind}{David Mosberger-Tang}{Programming Library}{Introduction to libunwind}libunwind -- a (mostly) platform-independent unwind API
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\noindent
\Type{int} \Func{unw\_getcontext}(\Type{unw\_context\_t~*});\\
\noindent
\Type{int} \Func{unw\_init\_local}(\Type{unw\_cursor\_t~*}, \Type{unw\_context\_t~*});\\
\noindent
\Type{int} \Func{unw\_init\_remote}(\Type{unw\_cursor\_t~*}, \Type{unw\_addr\_space\_t}, \Type{void~*});\\
\noindent
\Type{int} \Func{unw\_step}(\Type{unw\_cursor\_t~*});\\
\noindent
\Type{int} \Func{unw\_get\_reg}(\Type{unw\_cursor\_t~*}, \Type{unw\_regnum\_t}, \Type{unw\_word\_t~*});\\
\noindent
\Type{int} \Func{unw\_get\_fpreg}(\Type{unw\_cursor\_t~*}, \Type{unw\_regnum\_t}, \Type{unw\_fpreg\_t~*});\\
\noindent
\Type{int} \Func{unw\_set\_reg}(\Type{unw\_cursor\_t~*}, \Type{unw\_regnum\_t}, \Type{unw\_word\_t});\\
\noindent
\Type{int} \Func{unw\_set\_fpreg}(\Type{unw\_cursor\_t~*}, \Type{unw\_regnum\_t}, \Type{unw\_fpreg\_t});\\
\noindent
\Type{int} \Func{unw\_resume}(\Type{unw\_cursor\_t~*});\\
\noindent
\Type{unw\_addr\_space\_t} \Var{unw\_local\_addr\_space};\\
\noindent
\Type{unw\_addr\_space\_t} \Func{unw\_create\_addr\_space}(\Type{unw\_accessors\_t}, \Type{int});\\
\noindent
\Type{void} \Func{unw\_destroy\_addr\_space}(\Type{unw\_addr\_space\_t});\\
\noindent
\Type{unw\_accessors\_t} \Func{unw\_get\_accessors}(\Type{unw\_addr\_space\_t});\\
\noindent
\Type{void} \Func{unw\_flush\_cache}(\Type{unw\_addr\_space\_t}, \Type{unw\_word\_t}, \Type{unw\_word\_t});\\
\noindent
\Type{int} \Func{unw\_set\_caching\_policy}(\Type{unw\_addr\_space\_t}, \Type{unw\_caching\_policy\_t});\\
\noindent
\Type{const char *}\Func{unw\_regname}(\Type{unw\_regnum\_t});\\
\noindent
\Type{int} \Func{unw\_get\_proc\_info}(\Type{unw\_cursor\_t~*}, \Type{unw\_proc\_info\_t~*});\\
\noindent
\Type{int} \Func{unw\_get\_save\_loc}(\Type{unw\_cursor\_t~*}, \Type{int}, \Type{unw\_save\_loc\_t~*});\\
\noindent
\Type{int} \Func{unw\_is\_fpreg}(\Type{unw\_regnum\_t});\\
\Type{int} \Func{unw\_is\_signal\_frame}(\Type{unw\_cursor\_t~*});\\
\noindent
\Type{int} \Func{unw\_get\_proc\_name}(\Type{unw\_cursor\_t~*}, \Type{char~*}, \Type{size\_t}, \Type{unw\_word\_t~*});\\
\noindent
\Type{void} \Func{\_U\_dyn\_register}(\Type{unw\_dyn\_info\_t~*});\\
\noindent
\Type{void} \Func{\_U\_dyn\_cancel}(\Type{unw\_dyn\_info\_t~*});\\
\section{Local Unwinding}
\Prog{Libunwind} is very easy to use when unwinding a stack from
within a running program. This is called \emph{local} unwinding. Say
you want to unwind the stack while executing in some function
\Func{F}(). In this function, you would call \Func{unw\_getcontext}()
to get a snapshot of the CPU registers (machine-state). Then you
initialize an \emph{unwind~cursor} based on this snapshot. This is
done with a call to \Func{unw\_init\_local}(). The cursor now points
to the current frame, that is, the stack frame that corresponds to the
current activation of function \Func{F}(). The unwind cursor can then
be moved ``up'' (towards earlier stack frames) by calling
\Func{unw\_step}(). By repeatedly calling this routine, you can
uncover the entire call-chain that led to the activation of function
\Func{F}(). A positive return value from \Func{unw\_step}() indicates
that there are more frames in the chain, zero indicates that the end
of the chain has been reached, and any negative value indicates that
some sort of error has occurred.
While it is not possible to directly move the unwind cursor in the
``down'' direction (towards newer stack frames), this effect can be
achieved by making copies of an unwind cursor. For example, a program
that sometimes has to move ``down'' by one stack frame could maintain
two cursor variables: ``\Var{curr}'' and ``\Var{prev}''. The former
would be used as the current cursor and \Var{prev} would be maintained
as the ``previous frame'' cursor by copying the contents of \Var{curr}
to \Var{prev} right before calling \Func{unw\_step}(). With this
approach, the program could move one step ``down'' simply by copying
back \Var{prev} to \Var{curr} whenever that is necessary. In the most
extreme case, a program could maintain a separate cursor for each call
frame and that way it could move up and down the callframe-chain at
will.
Given an unwind cursor, it is possible to read and write the CPU
registers that were preserved for the current stack frame (as
identified by the cursor). \Prog{Libunwind} provides several routines
for this purpose: \Func{unw\_get\_reg}() reads an integer (general)
register, \Func{unw\_get\_fpreg}() reads a floating-point register,
\Func{unw\_set\_reg}() writes an integer register, and
\Func{unw\_set\_fpreg}() writes a floating-point register. Note that,
by definition, only the \emph{preserved} machine state can be accessed
during an unwind operation. Normally, this state consists of the
\emph{callee-saved} (``preserved'') registers. However, in some
special circumstances (e.g., in a signal handler trampoline), even the
\emph{caller-saved} (``scratch'') registers are preserved in the stack
frame and, in those cases, \Prog{libunwind} will grant access to them
as well. The exact set of registers that can be accessed via the
cursor depends, of course, on the platform. However, there are two
registers that can be read on all platforms: the instruction pointer
(IP), sometimes also known as the ``program counter'', and the stack
pointer (SP). In \Prog{libunwind}, these registers are identified by
the macros \Const{UNW\_REG\_IP} and \Const{UNW\_REG\_SP},
respectively.
Besides just moving the unwind cursor and reading/writing saved
registers, \Prog{libunwind} also provides the ability to resume
execution at an arbitrary stack frame. As you might guess, this is
useful for implementing non-local gotos and the exception handling
needed by some high-level languages such as Java. Resuming execution
with a particular stack frame simply requires calling
\Func{unw\_resume}() and passing the cursor identifying the target
frame as the only argument.
Normally, \Prog{libunwind} supports both local and remote unwinding
(the latter will be explained in the next section). However, if you
tell libunwind that your program only needs local unwinding, then a
special implementation can be selected which may run much faster than
the generic implementation which supports both kinds of unwinding. To
select this optimized version, simply define the macro
\Const{UNW\_LOCAL\_ONLY} before including the headerfile
\File{$<$libunwind.h$>$}. It is perfectly OK for a single program to
employ both local-only and generic unwinding. That is, whether or not
\Const{UNW\_LOCAL\_ONLY} is defined is a choice that each source-file
(compilation-unit) can make on its own. Independent of the setting(s)
of \Const{UNW\_LOCAL\_ONLY}, you'll always link the same library into
the program (normally \Opt{-l}\File{unwind}). Furthermore, the
portion of \Prog{libunwind} that manages unwind-info for dynamically
generated code is not affected by the setting of
\Const{UNW\_LOCAL\_ONLY}.
If we put all of the above together, here is how we could use
\Prog{libunwind} to write a function ``\Func{show\_backtrace}()''
which prints a classic stack trace:
\begin{verbatim}
#define UNW_LOCAL_ONLY
#include <libunwind.h>
void show_backtrace (void) {
unw_cursor_t cursor; unw_context_t uc;
unw_word_t ip, sp;
unw_getcontext(&uc);
unw_init_local(&cursor, &uc);
while (unw_step(&cursor) > 0) {
unw_get_reg(&cursor, UNW_REG_IP, &ip);
unw_get_reg(&cursor, UNW_REG_SP, &sp);
printf ("ip = %lx, sp = %lx\n", (long) ip, (long) sp);
}
}
\end{verbatim}
\section{Remote Unwinding}
\Prog{Libunwind} can also be used to unwind a stack in a ``remote''
process. Here, ``remote'' may mean another process on the same
machine or even a process on a completely different machine from the
one that is running \Prog{libunwind}. Remote unwinding is typically
used by debuggers and instruction-set simulators, for example.
Before you can unwind a remote process, you need to create a new
address-space object for that process. This is achieved with the
\Func{unw\_create\_addr\_space}() routine. The routine takes two
arguments: a pointer to a set of \emph{accessor} routines and an
integer that specifies the byte-order of the target process. The
accessor routines provide \Func{libunwind} with the means to
communicate with the remote process. In particular, there are
callbacks to read and write the process's memory, its registers, and
to access unwind information which may be needed by \Func{libunwind}.
With the address space created, unwinding can be initiated by a call
to \Func{unw\_init\_remote}(). This routine is very similar to
\Func{unw\_init\_local}(), except that it takes an address-space
object and an opaque pointer as arguments. The routine uses these
arguments to fetch the initial machine state. \Prog{Libunwind} never
uses the opaque pointer on its own, but instead just passes it on to
the accessor (callback) routines. Typically, this pointer is used to
select, e.g., the thread within a process that is to be unwound.
Once a cursor has been initialized with \Func{unw\_init\_remote}(),
unwinding works exactly like in the local case. That is, you can use
\Func{unw\_step}() to move ``up'' in the call-chain, read and write
registers, or resume execution at a particular stack frame by calling
\Func{unw\_resume}.
\section{Cross-platform and Multi-platform Unwinding}
\Prog{Libunwind} has been designed to enable unwinding across
platforms (architectures). Indeed, a single program can use
\Prog{libunwind} to unwind an arbitrary number of target platforms,
all at the same time!
We call the machine that is running \Prog{libunwind} the \emph{host}
and the machine that is running the process being unwound the
\emph{target}. If the host and the target platform are the same, we
call it \emph{native} unwinding. If they differ, we call it
\emph{cross-platform} unwinding.
The principle behind supporting native, cross-platform, and
multi-platform unwinding is very simple: for native unwinding, a
program includes \File{$<$libunwind.h$>$} and uses the linker switch
\Opt{-l}\File{unwind}. For cross-platform unwinding, a program
includes \File{$<$libunwind-}\Var{PLAT}\File{.h$>$} and uses the linker
switch \Opt{-l}\File{unwind-}\Var{PLAT}, where \Var{PLAT} is the name
of the target platform (e.g., \File{ia64} for IA-64, \File{hppa-elf}
for ELF-based HP PA-RISC, or \File{x86} for 80386). Multi-platform
unwinding works exactly like cross-platform unwinding, the only
limitation is that a single source file (compilation unit) can include
at most one \Prog{libunwind} header file. In other words, the
platform-specific support for each supported target needs to be
isolated in separate source files---a limitation that shouldn't be an
issue in practice.
Note that, by definition, local unwinding is possible only for the
native case. Attempting to call, e.g., \Func{unw\_local\_init}() when
targeting a cross-platform will result in a link-time error
(unresolved references).
\section{Thread- and Signal-Safety}
All \Prog{libunwind} routines are thread-safe. What this means is
that multiple threads may use \Prog{libunwind} simulatenously.
However, any given cursor may be accessed by only one thread at
any given time.
To ensure thread-safety, some \Prog{libunwind} routines may have to
use locking. Such routines \emph{must~not} be called from signal
handlers (directly or indirectly) and are therefore \emph{not}
signal-safe. The manual page for each \Prog{libunwind} routine
identifies whether or not it is signal-safe, but as a general rule,
any routine that may be needed for \emph{local} unwinding is
signal-safe (e.g., \Func{unw\_step}() for local unwinding is
signal-safe). For remote-unwinding, \emph{none} of the
\Prog{libunwind} routines are guaranteed to be signal-safe.
\section{Unwinding Through Dynamically Generated Code}
\Func{Libunwind} provides the routines \Func{\_U\_dyn\_register}() and
\Func{\_U\_dyn\_cancel}() to register/cancel the information required to
unwind through code that has been generated at runtime (e.g., by a
just-in-time (JIT) compiler). It is important to register the
information for \emph{all} dynamically generated code because
otherwise, a debugger may not be able to function properly or
high-level language exception handling may not work as expected.
The interface for registering and canceling dynamic unwind info has
been designed for maximum efficiency, so as to minimize the
performance impact on JIT-compilers. In particular, both routines are
guaranteed to execute in ``constant time'' (O(1)) and the
data-structure encapsulating the dynamic unwind info has been designed
to facilitate sharing, such that similar procedures can share much of
the underlying information.
For more information on the \Prog{libunwind} support for dynamically
generated code, see \SeeAlso{libunwind-dynamic(3)}.
\section{Caching of Unwind Info}
To speed up execution, \Prog{libunwind} may aggressively cache the
information it needs to perform unwinding. If a process changes
during its lifetime, this creates a risk of \Prog{libunwind} using
stale data. For example, this would happen if \Prog{libunwind} were
to cache information about a shared library which later on gets
unloaded (e.g., via \Cmd{dlclose}{3}).
To prevent the risk of using stale data, \Prog{libunwind} provides two
facilities: first, it is possible to flush the cached information
associated with a specific address range in the target process (or the
entire address space, if desired). This functionality is provided by
\Func{unw\_flush\_cache}(). The second facility is provided by
\Func{unw\_set\_caching\_policy}(), which lets a program
select the exact caching policy in use for a given address-space
object. In particular, by selecting the policy
\Const{UNW\_CACHE\_NONE}, it is possible to turn off caching
completely, therefore eliminating the risk of stale data alltogether
(at the cost of slower execution). By default, caching is enabled for
local unwinding only.
\section{Files}
\begin{Description}
\item[\File{libunwind.h}] Headerfile to include for native (same
platform) unwinding.
\item[\File{libunwind-}\Var{PLAT}\File{.h}] Headerfile to include when
the unwind target runs on platform \Var{PLAT}. For example, to unwind
an IA-64 program, the header file \File{libunwind-ia64.h} should be
included.
\item[\Opt{-l}\File{unwind}] Linker-switch to add when building a
program that does native (same platform) unwinding.
\item[\Opt{-l}\File{unwind-}\Var{PLAT}] Linker-switch to add when
building a program that unwinds a program on platform \Var{PLAT}.
For example, to (cross-)unwind an IA-64 program, the linker switch
\File{-lunwind-ia64} should be added. Note: multiple such switches
may need to be specified for programs that can unwind programs on
multiple platforms.
\end{Description}
\section{See Also}
\SeeAlso{libunwind-dynamic(3)},
\SeeAlso{libunwind-ia64(3)},
\SeeAlso{libunwind-ptrace(3)},
\SeeAlso{libunwind-setjmp(3)},
\SeeAlso{unw\_create\_addr\_space(3)},
\SeeAlso{unw\_destroy\_addr\_space(3)},
\SeeAlso{unw\_flush\_cache(3)},
\SeeAlso{unw\_get\_accessors(3)},
\SeeAlso{unw\_get\_fpreg(3)},
\SeeAlso{unw\_get\_proc\_info(3)},
\SeeAlso{unw\_get\_proc\_name(3)},
\SeeAlso{unw\_get\_reg(3)},
\SeeAlso{unw\_getcontext(3)},
\SeeAlso{unw\_init\_local(3)},
\SeeAlso{unw\_init\_remote(3)},
\SeeAlso{unw\_is\_fpreg(3)},
\SeeAlso{unw\_is\_signal\_frame(3)},
\SeeAlso{unw\_regname(3)},
\SeeAlso{unw\_resume(3)},
\SeeAlso{unw\_set\_caching\_policy(3)},
\SeeAlso{unw\_set\_fpreg(3)},
\SeeAlso{unw\_set\_reg(3)},
\SeeAlso{unw\_step(3)},
\SeeAlso{unw\_strerror(3)},
\SeeAlso{\_U\_dyn\_register(3)},
\SeeAlso{\_U\_dyn\_cancel(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

34
sdk/cpprt/linux/libunwind/doc/libunwind.trans Normal file
View File

@ -0,0 +1,34 @@
$manMacro1a{'Type'} = $manMacro1a{File};
$manMacro1b{'Type'} = $manMacro1b{File};
$htmlMacro1a{'Type'} = $htmlMacro1a{File};
$htmlMacro1b{'Type'} = $htmlMacro1b{File};
$texiMacro1a{'Type'} = $texiMacro1a{File};
$texiMacro1b{'Type'} = $texiMacro1b{File};
$manMacro1a{'Func'} = $manMacro1a{Prog};
$manMacro1b{'Func'} = $manMacro1b{Prog};
$htmlMacro1a{'Func'} = $htmlMacro1a{Arg};
$htmlMacro1b{'Func'} = $htmlMacro1b{Arg};
$texiMacro1a{'Func'} = $texiMacro1a{Prog};
$texiMacro1b{'Func'} = $texiMacro1b{Prog};
$manMacro1a{'Var'} = $manMacro1a{Prog};
$manMacro1b{'Var'} = $manMacro1b{Prog};
$htmlMacro1a{'Var'} = $htmlMacro1a{Prog};
$htmlMacro1b{'Var'} = $htmlMacro1b{Prog};
$texiMacro1a{'Var'} = $texiMacro1a{Prog};
$texiMacro1b{'Var'} = $texiMacro1b{Prog};
$manMacro1a{'Const'} = $manMacro1a{File};
$manMacro1b{'Const'} = $manMacro1b{File};
$htmlMacro1a{'Const'} = $htmlMacro1a{File};
$htmlMacro1b{'Const'} = $htmlMacro1b{File};
$texiMacro1a{'Const'} = $texiMacro1a{File};
$texiMacro1b{'Const'} = $texiMacro1b{File};
$manMacro1a{'SeeAlso'} = $manMacro1a{File};
$manMacro1b{'SeeAlso'} = $manMacro1b{File};
# special handling of SeeAlso in latex2man, so that argument gets doubled:
$htmlMacro2a{'SeeAlso'} = "<a href=\"";
$htmlMacro2b{'SeeAlso'} = ".html\">$htmlMacro1a{File}";
$htmlMacro2c{'SeeAlso'} = "$htmlMacro1b{File}</a>";
$texiMacro1a{'SeeAlso'} = $texiMacro1a{File};
$texiMacro1b{'SeeAlso'} = $texiMacro1b{File};

457
sdk/cpprt/linux/libunwind/doc/unw_create_addr_space.man Normal file
View File

@ -0,0 +1,457 @@
'\" 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\\_CREATE\\_ADDR\\_SPACE" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_create_addr_space
\-\- create address space for remote unwinding
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
unw_addr_space_t
unw_create_addr_space(unw_accessors_t *ap,
int
byteorder);
.br
.PP
.SH DESCRIPTION
.PP
The unw_create_addr_space()
routine creates a new unwind
address\-space and initializes it based on the call\-back routines
passed via the ap
pointer and the specified byteorder\&.
The call\-back routines are described in detail below. The
byteorder
can be set to 0 to request the default byte\-order of
the unwind target. To request a particular byte\-order,
byteorder
can be set to any constant defined by
<endian.h>\&.
In particular, __LITTLE_ENDIAN
would
request little\-endian byte\-order and __BIG_ENDIAN
would
request big\-endian byte\-order. Whether or not a particular byte\-order
is supported depends on the target platform.
.PP
.SH CALL\-BACK ROUTINES
.PP
Libunwind
uses a set of call\-back routines to access the
information it needs to unwind a chain of stack\-frames. These
routines are specified via the ap
argument, which points to a
variable of type unw_accessors_t\&.
The contents of this
variable is copied into the newly\-created address space, so the
variable must remain valid only for the duration of the call to
unw_create_addr_space().
.PP
The first argument to every call\-back routine is an address\-space
identifier (as)
and the last argument is an arbitrary,
application\-specified void\-pointer (arg).
When invoking a
call\-back routine, libunwind
sets the as
argument to the
address\-space on whose behalf the invocation is made and the arg
argument to the value that was specified when
unw_init_remote(3)
was called.
.PP
The synopsis and a detailed description of every call\-back routine
follows below.
.PP
.SS CALL\-BACK ROUTINE SYNOPSIS
.PP
int
find_proc_info(unw_addr_space_t
as,
.br
\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_word_t
ip,
unw_proc_info_t *pip,
.br
\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPint
need_unwind_info,
void *arg);
.br
void
put_unwind_info(unw_addr_space_t
as,
.br
\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_proc_info_t *pip,
void *arg);
.br
int
get_dyn_info_list_addr(unw_addr_space_t
as,
.br
\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_word_t *dilap,
void *arg);
.br
int
access_mem(unw_addr_space_t
as,
.br
\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_word_t
addr,
unw_word_t *valp,
.br
\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPint
write,
void *arg);
.br
int
access_reg(unw_addr_space_t
as,
.br
\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_regnum_t
regnum,
unw_word_t *valp,
.br
\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPint
write,
void *arg);
.br
int
access_fpreg(unw_addr_space_t
as,
.br
\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_regnum_t
regnum,
unw_fpreg_t *fpvalp,
.br
\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPint
write,
void *arg);
.br
int
resume(unw_addr_space_t
as,
.br
\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_cursor_t *cp,
void *arg);
.br
int
get_proc_name(unw_addr_space_t
as,
.br
\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPunw_word_t
addr,
char *bufp,
.br
\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPsize_t
buf_len,
unw_word_t *offp,
.br
\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fP\fB \fPvoid *arg);
.br
.PP
.SS FIND_PROC_INFO
.PP
Libunwind
invokes the find_proc_info()
call\-back to
locate the information need to unwind a particular procedure. The
ip
argument is an instruction\-address inside the procedure whose
information is needed. The pip
argument is a pointer to the
variable used to return the desired information. The type of this
variable is unw_proc_info_t\&.
See
unw_get_proc_info(3)
for details. Argument
need_unwind_info
is zero if the call\-back does not need to
provide values for the following members in the
unw_proc_info_t
structure: format,
unwind_info_size,
and unwind_info\&.
If
need_unwind_info
is non\-zero, valid values need to be returned
in these members. Furthermore, the contents of the memory addressed
by the unwind_info
member must remain valid until the info is
released via the put_unwind_info
call\-back (see below).
.PP
On successful completion, the find_proc_info()
call\-back must
return zero. Otherwise, the negative value of one of the
unw_error_t
error\-codes may be returned. In particular, this
call\-back may return \-UNW_ESTOPUNWIND
to signal the end of
the frame\-chain.
.PP
.SS PUT_UNWIND_INFO
.PP
Libunwind
invokes the put_unwind_info()
call\-back to
release the resources (such as memory) allocated by a previous call to
find_proc_info()
with the need_unwind_info
argument
set to a non\-zero value. The pip
argument has the same value as
the argument of the same name in the previous matching call to
find_proc_info().
Note that libunwind
does \fInot\fP
invoke put_unwind_info
for calls to find_proc_info()
with a zero need_unwind_info
argument.
.PP
.SS GET_DYN_INFO_LIST_ADDR
.PP
Libunwind
invokes the get_dyn_info_list_addr()
call\-back to obtain the address of the head of the dynamic unwind\-info
registration list. The variable stored at the returned address must
have a type of unw_dyn_info_list_t
(see
_U_dyn_register(3)).
The dliap
argument is a pointer
to a variable of type unw_word_t
which is used to return the
address of the dynamic unwind\-info registration list. If no dynamic
unwind\-info registration list exist, the value pointed to by
dliap
must be cleared to zero. Libunwind
will cache the
value returned by get_dyn_info_list_addr()
if caching is
enabled for the given address\-space. The cache can be cleared with a
call to unw_flush_cache().
.PP
On successful completion, the get_dyn_info_list_addr()
call\-back must return zero. Otherwise, the negative value of one of
the unw_error_t
error\-codes may be returned.
.PP
.SS ACCESS_MEM
.PP
Libunwind
invokes the access_mem()
call\-back to read
from or write to a word of memory in the target address\-space. The
address of the word to be accessed is passed in argument addr\&.
To read memory, libunwind
sets argument write
to zero and
valp
to point to the word that receives the read value. To
write memory, libunwind
sets argument write
to a non\-zero
value and valp
to point to the word that contains the value to
be written. The word that valp
points to is always in the
byte\-order of the host\-platform, regardless of the byte\-order of the
target. In other words, it is the responsibility of the call\-back
routine to convert between the target\&'s and the host\&'s byte\-order, if
necessary.
.PP
On successful completion, the access_mem()
call\-back must return zero. Otherwise, the negative value of one of
the unw_error_t
error\-codes may be returned.
.PP
.SS ACCESS_REG
.PP
Libunwind
invokes the access_reg()
call\-back to read
from or write to a scalar (non\-floating\-point) CPU register. The
index of the register to be accessed is passed in argument
regnum\&.
To read a register, libunwind
sets argument
write
to zero and valp
to point to the word that receives
the read value. To write a register, libunwind
sets argument
write
to a non\-zero value and valp
to point to the word
that contains the value to be written. The word that valp
points to is always in the byte\-order of the host\-platform, regardless
of the byte\-order of the target. In other words, it is the
responsibility of the call\-back routine to convert between the
target\&'s and the host\&'s byte\-order, if necessary.
.PP
On successful completion, the access_reg()
call\-back must
return zero. Otherwise, the negative value of one of the
unw_error_t
error\-codes may be returned.
.PP
.SS ACCESS_FPREG
.PP
Libunwind
invokes the access_fpreg()
call\-back to read
from or write to a floating\-point CPU register. The index of the
register to be accessed is passed in argument regnum\&.
To read a
register, libunwind
sets argument write
to zero and
fpvalp
to point to a variable of type unw_fpreg_t
that
receives the read value. To write a register, libunwind
sets
argument write
to a non\-zero value and fpvalp
to point to
the variable of type unw_fpreg_t
that contains the value to
be written. The word that fpvalp
points to is always in the
byte\-order of the host\-platform, regardless of the byte\-order of the
target. In other words, it is the responsibility of the call\-back
routine to convert between the target\&'s and the host\&'s byte\-order, if
necessary.
.PP
On successful completion, the access_fpreg()
call\-back must
return zero. Otherwise, the negative value of one of the
unw_error_t
error\-codes may be returned.
.PP
.SS RESUME
.PP
Libunwind
invokes the resume()
call\-back to resume
execution in the target address space. Argument cp
is the
unwind\-cursor that identifies the stack\-frame in which execution
should resume. By the time libunwind
invokes the resume
call\-back, it has already established the desired machine\- and
memory\-state via calls to the access_reg(),
access_fpreg,
and access_mem()
call\-backs. Thus, all
the call\-back needs to do is perform whatever action is needed to
actually resume execution.
.PP
The resume
call\-back is invoked only in response to a call to
unw_resume(3),
so applications which never invoke
unw_resume(3)
need not define the resume
callback.
.PP
On successful completion, the resume()
call\-back must return
zero. Otherwise, the negative value of one of the
unw_error_t
error\-codes may be returned. As a special case,
when resuming execution in the local address space, the call\-back will
not return on success.
.PP
.SS GET_PROC_NAME
.PP
Libunwind
invokes the get_proc_name()
call\-back to
obtain the procedure\-name of a static (not dynamically generated)
procedure. Argument addr
is an instruction\-address within the
procedure whose name is to be obtained. The bufp
argument is a
pointer to a character\-buffer used to return the procedure name. The
size of this buffer is specified in argument buf_len\&.
The
returned name must be terminated by a NUL character. If the
procedure\&'s name is longer than buf_len
bytes, it must be
truncated to buf_len\-1
bytes, with the last byte in the
buffer set to the NUL character and \-UNW_ENOMEM
must be
returned. Argument offp
is a pointer to a word which is used to
return the byte\-offset relative to the start of the procedure whose
name is being returned. For example, if procedure foo()
starts
at address 0x40003000, then invoking get_proc_name()
with
addr
set to 0x40003080 should return a value of 0x80 in the word
pointed to by offp
(assuming the procedure is at least 0x80
bytes long).
.PP
On successful completion, the get_proc_name()
call\-back must
return zero. Otherwise, the negative value of one of the
unw_error_t
error\-codes may be returned.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_create_addr_space()
returns a
non\-NULL
value that represents the newly created
address\-space. Otherwise, NULL
is returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_create_addr_space()
is thread\-safe but \fInot\fP
safe to use from a signal handler.
.PP
.SH SEE ALSO
.PP
_U_dyn_register(3),
libunwind(3),
unw_destroy_addr_space(3),
unw_get_proc_info(3),
unw_init_remote(3),
unw_resume(3)
.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.

265
sdk/cpprt/linux/libunwind/doc/unw_create_addr_space.tex Normal file
View File

@ -0,0 +1,265 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_create\_addr\_space}{David Mosberger-Tang}{Programming Library}{unw\_create\_addr\_space}unw\_create\_addr\_space -- create address space for remote unwinding
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{unw\_addr\_space\_t} \Func{unw\_create\_addr\_space}(\Type{unw\_accessors\_t~*}\Var{ap}, \Type{int} \Var{byteorder});\\
\section{Description}
The \Func{unw\_create\_addr\_space}() routine creates a new unwind
address-space and initializes it based on the call-back routines
passed via the \Var{ap} pointer and the specified \Var{byteorder}.
The call-back routines are described in detail below. The
\Var{byteorder} can be set to 0 to request the default byte-order of
the unwind target. To request a particular byte-order,
\Var{byteorder} can be set to any constant defined by
\File{$<$endian.h$>$}. In particular, \Const{\_\_LITTLE\_ENDIAN} would
request little-endian byte-order and \Const{\_\_BIG\_ENDIAN} would
request big-endian byte-order. Whether or not a particular byte-order
is supported depends on the target platform.
\section{Call-back Routines}
\Prog{Libunwind} uses a set of call-back routines to access the
information it needs to unwind a chain of stack-frames. These
routines are specified via the \Var{ap} argument, which points to a
variable of type \Type{unw\_accessors\_t}. The contents of this
variable is copied into the newly-created address space, so the
variable must remain valid only for the duration of the call to
\Func{unw\_create\_addr\_space}().
The first argument to every call-back routine is an address-space
identifier (\Var{as}) and the last argument is an arbitrary,
application-specified void-pointer (\Var{arg}). When invoking a
call-back routine, \Prog{libunwind} sets the \Var{as} argument to the
address-space on whose behalf the invocation is made and the \Var{arg}
argument to the value that was specified when
\Func{unw\_init\_remote}(3) was called.
The synopsis and a detailed description of every call-back routine
follows below.
\subsection{Call-back Routine Synopsis}
\Type{int} \Func{find\_proc\_info}(\Type{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_word\_t} \Var{ip}, \Type{unw\_proc\_info\_t~*}\Var{pip},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{int} \Var{need\_unwind\_info}, \Type{void~*}arg);\\
\Type{void} \Func{put\_unwind\_info}(\Type{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_proc\_info\_t~*}pip, \Type{void~*}\Var{arg});\\
\Type{int} \Func{get\_dyn\_info\_list\_addr}(\Type{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_word\_t~*}\Var{dilap}, \Type{void~*}\Var{arg});\\
\Type{int} \Func{access\_mem}(\Var{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_word\_t} \Var{addr}, \Type{unw\_word\_t~*}\Var{valp},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{int} \Var{write}, \Type{void~*}\Var{arg});\\
\Type{int} \Func{access\_reg}(\Var{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_regnum\_t} \Var{regnum}, \Type{unw\_word\_t~*}\Var{valp},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{int} \Var{write}, \Type{void~*}\Var{arg});\\
\Type{int} \Func{access\_fpreg}(\Var{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_regnum\_t} \Var{regnum}, \Type{unw\_fpreg\_t~*}\Var{fpvalp},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{int} \Var{write}, \Type{void~*}\Var{arg});\\
\Type{int} \Func{resume}(\Var{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_cursor\_t~*}\Var{cp}, \Type{void~*}\Var{arg});\\
\Type{int} \Func{get\_proc\_name}(\Type{unw\_addr\_space\_t} \Var{as},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{unw\_word\_t} \Var{addr}, \Type{char~*}\Var{bufp},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{size\_t} \Var{buf\_len}, \Type{unw\_word\_t~*}\Var{offp},\\
\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\SP\Type{void~*}\Var{arg});\\
\subsection{find\_proc\_info}
\Prog{Libunwind} invokes the \Func{find\_proc\_info}() call-back to
locate the information need to unwind a particular procedure. The
\Var{ip} argument is an instruction-address inside the procedure whose
information is needed. The \Var{pip} argument is a pointer to the
variable used to return the desired information. The type of this
variable is \Type{unw\_proc\_info\_t}. See
\Func{unw\_get\_proc\_info(3)} for details. Argument
\Var{need\_unwind\_info} is zero if the call-back does not need to
provide values for the following members in the
\Type{unw\_proc\_info\_t} structure: \Var{format},
\Var{unwind\_info\_size}, and \Var{unwind\_info}. If
\Var{need\_unwind\_info} is non-zero, valid values need to be returned
in these members. Furthermore, the contents of the memory addressed
by the \Var{unwind\_info} member must remain valid until the info is
released via the \Func{put\_unwind\_info} call-back (see below).
On successful completion, the \Func{find\_proc\_info}() call-back must
return zero. Otherwise, the negative value of one of the
\Type{unw\_error\_t} error-codes may be returned. In particular, this
call-back may return -\Const{UNW\_ESTOPUNWIND} to signal the end of
the frame-chain.
\subsection{put\_unwind\_info}
\Prog{Libunwind} invokes the \Func{put\_unwind\_info}() call-back to
release the resources (such as memory) allocated by a previous call to
\Func{find\_proc\_info}() with the \Var{need\_unwind\_info} argument
set to a non-zero value. The \Var{pip} argument has the same value as
the argument of the same name in the previous matching call to
\Func{find\_proc\_info}(). Note that \Prog{libunwind} does \emph{not}
invoke \Func{put\_unwind\_info} for calls to \Func{find\_proc\_info}()
with a zero \Var{need\_unwind\_info} argument.
\subsection{get\_dyn\_info\_list\_addr}
\Prog{Libunwind} invokes the \Func{get\_dyn\_info\_list\_addr}()
call-back to obtain the address of the head of the dynamic unwind-info
registration list. The variable stored at the returned address must
have a type of \Type{unw\_dyn\_info\_list\_t} (see
\Func{\_U\_dyn\_register}(3)). The \Var{dliap} argument is a pointer
to a variable of type \Type{unw\_word\_t} which is used to return the
address of the dynamic unwind-info registration list. If no dynamic
unwind-info registration list exist, the value pointed to by
\Var{dliap} must be cleared to zero. \Prog{Libunwind} will cache the
value returned by \Func{get\_dyn\_info\_list\_addr}() if caching is
enabled for the given address-space. The cache can be cleared with a
call to \Func{unw\_flush\_cache}().
On successful completion, the \Func{get\_dyn\_info\_list\_addr}()
call-back must return zero. Otherwise, the negative value of one of
the \Type{unw\_error\_t} error-codes may be returned.
\subsection{access\_mem}
\Prog{Libunwind} invokes the \Func{access\_mem}() call-back to read
from or write to a word of memory in the target address-space. The
address of the word to be accessed is passed in argument \Var{addr}.
To read memory, \Prog{libunwind} sets argument \Var{write} to zero and
\Var{valp} to point to the word that receives the read value. To
write memory, \Prog{libunwind} sets argument \Var{write} to a non-zero
value and \Var{valp} to point to the word that contains the value to
be written. The word that \Var{valp} points to is always in the
byte-order of the host-platform, regardless of the byte-order of the
target. In other words, it is the responsibility of the call-back
routine to convert between the target's and the host's byte-order, if
necessary.
On successful completion, the \Func{access\_mem}()
call-back must return zero. Otherwise, the negative value of one of
the \Type{unw\_error\_t} error-codes may be returned.
\subsection{access\_reg}
\Prog{Libunwind} invokes the \Func{access\_reg}() call-back to read
from or write to a scalar (non-floating-point) CPU register. The
index of the register to be accessed is passed in argument
\Var{regnum}. To read a register, \Prog{libunwind} sets argument
\Var{write} to zero and \Var{valp} to point to the word that receives
the read value. To write a register, \Prog{libunwind} sets argument
\Var{write} to a non-zero value and \Var{valp} to point to the word
that contains the value to be written. The word that \Var{valp}
points to is always in the byte-order of the host-platform, regardless
of the byte-order of the target. In other words, it is the
responsibility of the call-back routine to convert between the
target's and the host's byte-order, if necessary.
On successful completion, the \Func{access\_reg}() call-back must
return zero. Otherwise, the negative value of one of the
\Type{unw\_error\_t} error-codes may be returned.
\subsection{access\_fpreg}
\Prog{Libunwind} invokes the \Func{access\_fpreg}() call-back to read
from or write to a floating-point CPU register. The index of the
register to be accessed is passed in argument \Var{regnum}. To read a
register, \Prog{libunwind} sets argument \Var{write} to zero and
\Var{fpvalp} to point to a variable of type \Type{unw\_fpreg\_t} that
receives the read value. To write a register, \Prog{libunwind} sets
argument \Var{write} to a non-zero value and \Var{fpvalp} to point to
the variable of type \Type{unw\_fpreg\_t} that contains the value to
be written. The word that \Var{fpvalp} points to is always in the
byte-order of the host-platform, regardless of the byte-order of the
target. In other words, it is the responsibility of the call-back
routine to convert between the target's and the host's byte-order, if
necessary.
On successful completion, the \Func{access\_fpreg}() call-back must
return zero. Otherwise, the negative value of one of the
\Type{unw\_error\_t} error-codes may be returned.
\subsection{resume}
\Prog{Libunwind} invokes the \Func{resume}() call-back to resume
execution in the target address space. Argument \Var{cp} is the
unwind-cursor that identifies the stack-frame in which execution
should resume. By the time \Prog{libunwind} invokes the \Func{resume}
call-back, it has already established the desired machine- and
memory-state via calls to the \Func{access\_reg}(),
\Func{access\_fpreg}, and \Func{access\_mem}() call-backs. Thus, all
the call-back needs to do is perform whatever action is needed to
actually resume execution.
The \Func{resume} call-back is invoked only in response to a call to
\Func{unw\_resume}(3), so applications which never invoke
\Func{unw\_resume}(3) need not define the \Func{resume} callback.
On successful completion, the \Func{resume}() call-back must return
zero. Otherwise, the negative value of one of the
\Type{unw\_error\_t} error-codes may be returned. As a special case,
when resuming execution in the local address space, the call-back will
not return on success.
\subsection{get\_proc\_name}
\Prog{Libunwind} invokes the \Func{get\_proc\_name}() call-back to
obtain the procedure-name of a static (not dynamically generated)
procedure. Argument \Var{addr} is an instruction-address within the
procedure whose name is to be obtained. The \Var{bufp} argument is a
pointer to a character-buffer used to return the procedure name. The
size of this buffer is specified in argument \Var{buf\_len}. The
returned name must be terminated by a NUL character. If the
procedure's name is longer than \Var{buf\_len} bytes, it must be
truncated to \Var{buf\_len}\Prog{-1} bytes, with the last byte in the
buffer set to the NUL character and -\Const{UNW\_ENOMEM} must be
returned. Argument \Var{offp} is a pointer to a word which is used to
return the byte-offset relative to the start of the procedure whose
name is being returned. For example, if procedure \Func{foo}() starts
at address 0x40003000, then invoking \Func{get\_proc\_name}() with
\Var{addr} set to 0x40003080 should return a value of 0x80 in the word
pointed to by \Var{offp} (assuming the procedure is at least 0x80
bytes long).
On successful completion, the \Func{get\_proc\_name}() call-back must
return zero. Otherwise, the negative value of one of the
\Type{unw\_error\_t} error-codes may be returned.
\section{Return Value}
On successful completion, \Func{unw\_create\_addr\_space}() returns a
non-\Const{NULL} value that represents the newly created
address-space. Otherwise, \Const{NULL} is returned.
\section{Thread and Signal Safety}
\Func{unw\_create\_addr\_space}() is thread-safe but \emph{not}
safe to use from a signal handler.
\section{See Also}
\SeeAlso{\_U\_dyn\_register(3)},
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_destroy\_addr\_space(3)},
\SeeAlso{unw\_get\_proc\_info(3)},
\SeeAlso{unw\_init\_remote(3)},
\SeeAlso{unw\_resume(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

57
sdk/cpprt/linux/libunwind/doc/unw_destroy_addr_space.man Normal file
View File

@ -0,0 +1,57 @@
'\" 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\\_DESTROY\\_ADDR\\_SPACE" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_destroy_addr_space
\-\- destroy unwind address space
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
void
unw_destroy_addr_space(unw_addr_space_t
as);
.br
.PP
.SH DESCRIPTION
.PP
The unw_destroy_addr_space()
routine destroys the
address space specified by argument as
and thereby releases
all associated resources (such as memory).
.PP
Applications must not destroy the local address space
unw_local_addr_space\&.
Attempting to do so results in
undefined behavior (e.g., the application may crash).
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_create_addr_space(3)
.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.

40
sdk/cpprt/linux/libunwind/doc/unw_destroy_addr_space.tex Normal file
View File

@ -0,0 +1,40 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_destroy\_addr\_space}{David Mosberger-Tang}{Programming Library}{unw\_destroy\_addr\_space}unw\_destroy\_addr\_space -- destroy unwind address space
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{void} \Func{unw\_destroy\_addr\_space}(\Type{unw\_addr\_space\_t} \Var{as});\\
\section{Description}
The \Func{unw\_destroy\_addr\_space}() routine destroys the
address space specified by argument \Var{as} and thereby releases
all associated resources (such as memory).
Applications must not destroy the local address space
\Var{unw\_local\_addr\_space}. Attempting to do so results in
undefined behavior (e.g., the application may crash).
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_create\_addr\_space(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

92
sdk/cpprt/linux/libunwind/doc/unw_flush_cache.man Normal file
View File

@ -0,0 +1,92 @@
'\" t
.\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "UNW\\_FLUSH\\_CACHE" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_flush_cache
\-\- flush cached info
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
void
unw_flush_cache(unw_addr_space_t
as,
unw_word_t
lo,
unw_word_t
hi);
.br
.PP
.SH DESCRIPTION
.PP
The unw_flush_cache()
routine flushes all cached info as it
relates to address\-range lo
to hi
(non\-inclusive) in the
target address\-space as\&.
In addition, all info cached for
address\-space as
that is not tied to a particular code\-range is
also flushed. For example, the address of the dynamic registration
list is not tied to a code\-range and its cached value (if any) is
flushed by a call to this routine. The address range specified by
lo
and hi
should be understood as a hint:
unw_flush_cache()
may flush more information than requested,
but \fInever\fP
less. In other words, unw_flush_cache()
may
overflush, but not underflush.
.PP
As a special case, if arguments lo
and hi
are both 0, all
information cached on behalf of address space as
is flushed.
.PP
.SH RETURN VALUE
.PP
The unw_flush_cache()
routine cannot fail and does not
return a value.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
The unw_flush_cache()
routine is thread\-safe as well as safe to
use from a signal handler.
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_set_caching_policy(3)
.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.

57
sdk/cpprt/linux/libunwind/doc/unw_flush_cache.tex Normal file
View File

@ -0,0 +1,57 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_flush\_cache}{David Mosberger-Tang}{Programming Library}{unw\_flush\_cache}unw\_flush\_cache -- flush cached info
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{void} \Func{unw\_flush\_cache}(\Type{unw\_addr\_space\_t} \Var{as}, \Type{unw\_word\_t} \Var{lo}, \Type{unw\_word\_t} \Var{hi});\\
\section{Description}
The \Func{unw\_flush\_cache}() routine flushes all cached info as it
relates to address-range \Var{lo} to \Var{hi} (non-inclusive) in the
target address-space \Var{as}. In addition, all info cached for
address-space \Var{as} that is not tied to a particular code-range is
also flushed. For example, the address of the dynamic registration
list is not tied to a code-range and its cached value (if any) is
flushed by a call to this routine. The address range specified by
\Var{lo} and \Var{hi} should be understood as a hint:
\Func{unw\_flush\_cache}() may flush more information than requested,
but \emph{never} less. In other words, \Func{unw\_flush\_cache}() may
overflush, but not underflush.
As a special case, if arguments \Var{lo} and \Var{hi} are both 0, all
information cached on behalf of address space \Var{as} is flushed.
\section{Return Value}
The \Func{unw\_flush\_cache}() routine cannot fail and does not
return a value.
\section{Thread and Signal Safety}
The \Func{unw\_flush\_cache}() routine is thread-safe as well as safe to
use from a signal handler.
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_set\_caching\_policy(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

79
sdk/cpprt/linux/libunwind/doc/unw_get_accessors.man Normal file
View File

@ -0,0 +1,79 @@
'\" t
.\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "UNW\\_GET\\_ACCESSORS" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_get_accessors
\-\- get pointer to accessor call\-backs
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
unw_accessors_t *unw_get_accessors(unw_addr_space_t as);
.br
.PP
.SH DESCRIPTION
.PP
The unw_get_accessors()
routine returns a pointer to a
unw_accessors_t
structure, which contains the call\-back
routines that were specified when address space as
was created
(see unw_create_addr_space(3)).
The returned pointer is
guaranteed to remain valid until address space as
is destroyed
by a call to unw_destroy_addr_space(3).
.PP
Note that unw_get_accessors()
can be used to retrieve the
call\-back routines for the local address space
unw_local_addr_space\&.
.PP
.SH RETURN VALUE
.PP
The unw_get_accessors()
routine cannot fail and always
returns a valid (non\-NULL)
pointer to an
unw_accessors_t
structure.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
The unw_get_accessors()
routine is thread\-safe as well as
safe to use from a signal handler.
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_create_addr_space(3),
unw_destroy_addr_space(3)
.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.

55
sdk/cpprt/linux/libunwind/doc/unw_get_accessors.tex Normal file
View File

@ -0,0 +1,55 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_get\_accessors}{David Mosberger-Tang}{Programming Library}{unw\_get\_accessors}unw\_get\_accessors -- get pointer to accessor call-backs
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{unw\_accessors\_t~*}\Func{unw\_get\_accessors}(\Type{unw\_addr\_space\_t~}\Var{as});\\
\section{Description}
The \Func{unw\_get\_accessors}() routine returns a pointer to a
\Type{unw\_accessors\_t} structure, which contains the call-back
routines that were specified when address space \Var{as} was created
(see \Func{unw\_create\_addr\_space}(3)). The returned pointer is
guaranteed to remain valid until address space \Var{as} is destroyed
by a call to \Func{unw\_destroy\_addr\_space}(3).
Note that \Func{unw\_get\_accessors}() can be used to retrieve the
call-back routines for the local address space
\Var{unw\_local\_addr\_space}.
\section{Return Value}
The \Func{unw\_get\_accessors}() routine cannot fail and always
returns a valid (non-\Const{NULL}) pointer to an
\Type{unw\_accessors\_t} structure.
\section{Thread and Signal Safety}
The \Func{unw\_get\_accessors}() routine is thread-safe as well as
safe to use from a signal handler.
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_create\_addr\_space(3)},
\SeeAlso{unw\_destroy\_addr\_space(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

111
sdk/cpprt/linux/libunwind/doc/unw_get_fpreg.man Normal file
View File

@ -0,0 +1,111 @@
'\" 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\\_GET\\_FPREG" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_get_fpreg
\-\- get contents of floating\-point register
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_get_fpreg(unw_cursor_t *cp,
unw_regnum_t
reg,
unw_fpreg_t *valp);
.br
.PP
.SH DESCRIPTION
.PP
The unw_get_fpreg()
routine reads the value of floating\-point
register reg
in the stack frame identified by cursor cp
and stores the value in the variable pointed to by valp\&.
.PP
The register numbering is target\-dependent and described in separate
manual pages (e.g., libunwind\-ia64(3) for the IA\-64 target).
Furthermore, the exact set of accessible registers may depend on the
type of frame that cp
is referring to. For ordinary stack
frames, it is normally possible to access only the preserved
(``callee\-saved\&'') registers and frame\-related registers (such as the
stack\-pointer). However, for signal frames (see
unw_is_signal_frame(3)),
it is usually possible to access
all registers.
.PP
Note that unw_get_fpreg()
can only read the contents of
floating\-point registers. See unw_get_fpreg(3)
for a way to
read registers which fit in a single word.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_get_fpreg()
returns 0.
Otherwise the negative value of one of the error\-codes below is
returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_get_fpreg()
is thread\-safe as well as safe to use
from a signal handler.
.PP
.SH ERRORS
.PP
.TP
UNW_EUNSPEC
An unspecified error occurred.
.TP
UNW_EBADREG
An attempt was made to read a register
that is either invalid or not accessible in the current frame.
.PP
In addition, unw_get_fpreg()
may return any error returned by
the access_mem(),
access_reg(),
and
access_fpreg()
call\-backs (see
unw_create_addr_space(3)).
.PP
.SH SEE ALSO
.PP
libunwind(3),
libunwind\-ia64(3),
unw_get_reg(3),
unw_is_fpreg(3),
unw_is_signal_frame(3),
unw_set_fpreg(3)
.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.

77
sdk/cpprt/linux/libunwind/doc/unw_get_fpreg.tex Normal file
View File

@ -0,0 +1,77 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_get\_fpreg}{David Mosberger-Tang}{Programming Library}{unw\_get\_fpreg}unw\_get\_fpreg -- get contents of floating-point register
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_get\_fpreg}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{unw\_regnum\_t} \Var{reg}, \Type{unw\_fpreg\_t~*}\Var{valp});\\
\section{Description}
The \Func{unw\_get\_fpreg}() routine reads the value of floating-point
register \Var{reg} in the stack frame identified by cursor \Var{cp}
and stores the value in the variable pointed to by \Var{valp}.
The register numbering is target-dependent and described in separate
manual pages (e.g., libunwind-ia64(3) for the IA-64 target).
Furthermore, the exact set of accessible registers may depend on the
type of frame that \Var{cp} is referring to. For ordinary stack
frames, it is normally possible to access only the preserved
(``callee-saved'') registers and frame-related registers (such as the
stack-pointer). However, for signal frames (see
\Func{unw\_is\_signal\_frame}(3)), it is usually possible to access
all registers.
Note that \Func{unw\_get\_fpreg}() can only read the contents of
floating-point registers. See \Func{unw\_get\_fpreg}(3) for a way to
read registers which fit in a single word.
\section{Return Value}
On successful completion, \Func{unw\_get\_fpreg}() returns 0.
Otherwise the negative value of one of the error-codes below is
returned.
\section{Thread and Signal Safety}
\Func{unw\_get\_fpreg}() is thread-safe as well as safe to use
from a signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item[\Const{UNW\_EBADREG}] An attempt was made to read a register
that is either invalid or not accessible in the current frame.
\end{Description}
In addition, \Func{unw\_get\_fpreg}() may return any error returned by
the \Func{access\_mem}(), \Func{access\_reg}(), and
\Func{access\_fpreg}() call-backs (see
\Func{unw\_create\_addr\_space}(3)).
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{libunwind-ia64(3)},
\SeeAlso{unw\_get\_reg(3)},
\SeeAlso{unw\_is\_fpreg(3)},
\SeeAlso{unw\_is\_signal\_frame(3)},
\SeeAlso{unw\_set\_fpreg(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

203
sdk/cpprt/linux/libunwind/doc/unw_get_proc_info.man Normal file
View File

@ -0,0 +1,203 @@
'\" t
.\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "UNW\\_GET\\_PROC\\_INFO" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_get_proc_info
\-\- get info on current procedure
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_get_proc_info(unw_cursor_t *cp,
unw_proc_info_t *pip);
.br
.PP
.SH DESCRIPTION
.PP
The unw_get_proc_info()
routine returns auxiliary
information about the procedure that created the stack frame
identified by argument cp\&.
The pip
argument is a pointer
to a structure of type unw_proc_info_t
which is used to
return the information. The unw_proc_info_t
has the
following members:
.TP
unw_word_t start_ip
The address of the first
instruction of the procedure. If this address cannot be determined
(e.g., due to lack of unwind information), the start_ip
member is cleared to 0.
.br
.TP
unw_word_t end_ip
The address of the first
instruction \fIbeyond\fP
the end of the procedure. If this address
cannot be determined (e.g., due to lack of unwind information),
the end_ip
member is cleared to 0.
.br
.TP
unw_word_t lsda
The address of the
language\-specific data\-area (LSDA). This area normally contains
language\-specific information needed during exception handling. If
the procedure has no such area, this member is cleared to 0.
.br
.TP
unw_word_t handler
The address of the exception
handler routine. This is sometimes called the \fIpersonality\fP
routine. If the procedure does not define
a personality routine, the handler
member is cleared to 0.
.br
.TP
unw_word_t gp
The global\-pointer of the
procedure. On platforms that do not use a global pointer, this
member may contain an undefined value. On all other platforms, it
must be set either to the correct global\-pointer value of the
procedure or to 0 if the proper global\-pointer cannot be
obtained for some reason.
.br
.TP
unw_word_t flags
A set of flags. There are
currently no target\-independent flags. For the IA\-64 target, the
flag UNW_PI_FLAG_IA64_RBS_SWITCH
is set if the
procedure may switch the register\-backing store.
.br
.TP
int format
The format of the unwind\-info for this
procedure. If the unwind\-info consists of dynamic procedure info,
format
is equal to UNW_INFO_FORMAT_DYNAMIC\&.
If the
unwind\-info consists of a (target\-specific) unwind table, it is
equal to to UNW_INFO_FORMAT_TABLE\&.
All other values are
reserved for future use by libunwind\&.
This member exists
for use by the find_proc_info()
call\-back (see
unw_create_addr_space(3)).
The
unw_get_proc_info()
routine
may return an undefined value in this member.
.br
.TP
int unwind_info_size
The size of the unwind\-info
in bytes. This member exists for use by the
find_proc_info()
call\-back (see
unw_create_addr_space(3)).
The
unw_get_proc_info()
routine
may return an undefined value in this member.
.br
.TP
void *unwind_info
The pointer to the unwind\-info.
If no unwind info is available, this member must be set to
NULL\&.
This member exists for use by the
find_proc_info()
call\-back (see
unw_create_addr_space(3)).
The
unw_get_proc_info()
routine
may return an undefined value in this member.
.br
.PP
Note that for the purposes of libunwind,
the code of a
procedure is assumed to occupy a single, contiguous range of
addresses. For this reason, it is alwas possible to describe the
extent of a procedure with the start_ip
and end_ip
members. If a single function/routine is split into multiple,
discontiguous pieces, libunwind
will treat each piece as a
separate procedure.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_get_proc_info()
returns 0.
Otherwise the negative value of one of the error\-codes below is
returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_get_proc_info()
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_ENOINFO
Libunwind
was unable to locate
unwind\-info for the procedure.
.TP
UNW_EBADVERSION
The unwind\-info for the procedure has
version or format that is not understood by libunwind\&.
.PP
In addition, unw_get_proc_info()
may return any error
returned by the access_mem()
call\-back (see
unw_create_addr_space(3)).
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_create_addr_space(3),
unw_get_proc_name(3)
.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.

123
sdk/cpprt/linux/libunwind/doc/unw_get_proc_info.tex Normal file
View File

@ -0,0 +1,123 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_get\_proc\_info}{David Mosberger-Tang}{Programming Library}{unw\_get\_proc\_info}unw\_get\_proc\_info -- get info on current procedure
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_get\_proc\_info}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{unw\_proc\_info\_t~*}\Var{pip});\\
\section{Description}
The \Func{unw\_get\_proc\_info}() routine returns auxiliary
information about the procedure that created the stack frame
identified by argument \Var{cp}. The \Var{pip} argument is a pointer
to a structure of type \Type{unw\_proc\_info\_t} which is used to
return the information. The \Type{unw\_proc\_info\_t} has the
following members:
\begin{description}
\item[\Type{unw\_word\_t} \Var{start\_ip}] The address of the first
instruction of the procedure. If this address cannot be determined
(e.g., due to lack of unwind information), the \Var{start\_ip}
member is cleared to 0. \\
\item[\Type{unw\_word\_t} \Var{end\_ip}] The address of the first
instruction \emph{beyond} the end of the procedure. If this address
cannot be determined (e.g., due to lack of unwind information),
the \Var{end\_ip} member is cleared to 0. \\
\item[\Type{unw\_word\_t} \Var{lsda}] The address of the
language-specific data-area (LSDA). This area normally contains
language-specific information needed during exception handling. If
the procedure has no such area, this member is cleared to 0. \\
\item[\Type{unw\_word\_t} \Var{handler}] The address of the exception
handler routine. This is sometimes called the \emph{personality}
routine. If the procedure does not define
a personality routine, the \Var{handler} member is cleared to 0. \\
\item[\Type{unw\_word\_t} \Var{gp}] The global-pointer of the
procedure. On platforms that do not use a global pointer, this
member may contain an undefined value. On all other platforms, it
must be set either to the correct global-pointer value of the
procedure or to 0 if the proper global-pointer cannot be
obtained for some reason. \\
\item[\Type{unw\_word\_t} \Var{flags}] A set of flags. There are
currently no target-independent flags. For the IA-64 target, the
flag \Const{UNW\_PI\_FLAG\_IA64\_RBS\_SWITCH} is set if the
procedure may switch the register-backing store.\\
\item[\Type{int} \Var{format}] The format of the unwind-info for this
procedure. If the unwind-info consists of dynamic procedure info,
\Var{format} is equal to \Const{UNW\_INFO\_FORMAT\_DYNAMIC}. If the
unwind-info consists of a (target-specific) unwind table, it is
equal to to \Const{UNW\_INFO\_FORMAT\_TABLE}. All other values are
reserved for future use by \Prog{libunwind}. This member exists
for use by the \Func{find\_proc\_info}() call-back (see
\Func{unw\_create\_addr\_space}(3)). The
\Func{unw\_get\_proc\_info}() routine
may return an undefined value in this member. \\
\item[\Type{int} \Var{unwind\_info\_size}] The size of the unwind-info
in bytes. This member exists for use by the
\Func{find\_proc\_info}() call-back (see
\Func{unw\_create\_addr\_space}(3)). The
\Func{unw\_get\_proc\_info}() routine
may return an undefined value in this member.\\
\item[\Type{void~*}\Var{unwind\_info}] The pointer to the unwind-info.
If no unwind info is available, this member must be set to
\Const{NULL}. This member exists for use by the
\Func{find\_proc\_info}() call-back (see
\Func{unw\_create\_addr\_space}(3)). The
\Func{unw\_get\_proc\_info}() routine
may return an undefined value in this member.\\
\end{description}
Note that for the purposes of \Prog{libunwind}, the code of a
procedure is assumed to occupy a single, contiguous range of
addresses. For this reason, it is alwas possible to describe the
extent of a procedure with the \Var{start\_ip} and \Var{end\_ip}
members. If a single function/routine is split into multiple,
discontiguous pieces, \Prog{libunwind} will treat each piece as a
separate procedure.
\section{Return Value}
On successful completion, \Func{unw\_get\_proc\_info}() returns 0.
Otherwise the negative value of one of the error-codes below is
returned.
\section{Thread and Signal Safety}
\Func{unw\_get\_proc\_info}() is thread-safe. If cursor \Var{cp} is
in the local address-space, this routine is also safe to use from a
signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to locate
unwind-info for the procedure.
\item[\Const{UNW\_EBADVERSION}] The unwind-info for the procedure has
version or format that is not understood by \Prog{libunwind}.
\end{Description}
In addition, \Func{unw\_get\_proc\_info}() may return any error
returned by the \Func{access\_mem}() call-back (see
\Func{unw\_create\_addr\_space}(3)).
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_create\_addr\_space(3)},
\SeeAlso{unw\_get\_proc\_name(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

134
sdk/cpprt/linux/libunwind/doc/unw_get_proc_info_by_ip.man Normal file
View File

@ -0,0 +1,134 @@
'\" 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\\_GET\\_PROC\\_INFO\\_BY\\_IP" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_get_proc_info_by_ip
\-\- get procedure info by IP
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_get_proc_info_by_ip(unw_addr_space_t as,
unw_word_t ip,
unw_proc_info_t *pip,
void *arg);
.br
.PP
.SH DESCRIPTION
.PP
The unw_get_proc_info_by_ip()
routine returns the same
kind of auxiliary information about a procedure as
unw_get_proc_info(),
except that the info is looked up by
instruction\-pointer (IP) instead of a cursor. This is more flexible
because it is possible to look up the info for an arbitrary procedure,
even if it is not part of the current call\-chain. However, since it
is more flexible, it also tends to run slower (and often much slower)
than unw_get_proc_info().
.PP
The routine expects the followins arguments: as
is the
address\-space in which the instruction\-pointer should be looked up.
For a look\-up in the local address\-space,
unw_local_addr_space
can be passed for this argument.
Argument ip
is the instruction\-pointer for which the procedure
info should be looked up and pip
is a pointer to a structure of
type unw_proc_info_t
which is used to return the info.
Lastly, arg
is the address\-space argument that should be used
when accessing the address\-space. It has the same purpose as the
argument of the same name for unw_init_remote().
When
accessing the local address\-space (first argument is
unw_local_addr_space),
NULL
must be passed for this
argument.
.PP
Note that for the purposes of libunwind,
the code of a
procedure is assumed to occupy a single, contiguous range of
addresses. For this reason, it is alwas possible to describe the
extent of a procedure with the start_ip
and end_ip
members. If a single function/routine is split into multiple,
discontiguous pieces, libunwind
will treat each piece as a
separate procedure.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_get_proc_info_by_ip()
returns 0. Otherwise the negative value of one of the error\-codes
below is returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_get_proc_info()
is thread\-safe. If the local
address\-space is passed in argument as,
this routine is also
safe to use from a signal handler.
.PP
.SH ERRORS
.PP
.TP
UNW_EUNSPEC
An unspecified error occurred.
.TP
UNW_ENOINFO
Libunwind
was unable to locate
unwind\-info for the procedure.
.TP
UNW_EBADVERSION
The unwind\-info for the procedure has
version or format that is not understood by libunwind\&.
.PP
In addition, unw_get_proc_info()
may return any error
returned by the access_mem()
call\-back (see
unw_create_addr_space(3)).
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_create_addr_space(3),
unw_get_proc_name(3),
unw_get_proc_info(3),
unw_init_remote(3)
.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.

91
sdk/cpprt/linux/libunwind/doc/unw_get_proc_info_by_ip.tex Normal file
View File

@ -0,0 +1,91 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_get\_proc\_info\_by\_ip}{David Mosberger-Tang}{Programming Library}{unw\_get\_proc\_info\_by\_ip}unw\_get\_proc\_info\_by\_ip -- get procedure info by IP
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_get\_proc\_info\_by\_ip}(\Type{unw\_addr\_space\_t~}\Var{as}, \Type{unw\_word\_t~}\Var{ip}, \Type{unw\_proc\_info\_t~*}\Var{pip}, \Type{void~*}\Var{arg});\\
\section{Description}
The \Func{unw\_get\_proc\_info\_by\_ip}() routine returns the same
kind of auxiliary information about a procedure as
\Func{unw\_get\_proc\_info}(), except that the info is looked up by
instruction-pointer (IP) instead of a cursor. This is more flexible
because it is possible to look up the info for an arbitrary procedure,
even if it is not part of the current call-chain. However, since it
is more flexible, it also tends to run slower (and often much slower)
than \Func{unw\_get\_proc\_info}().
The routine expects the followins arguments: \Var{as} is the
address-space in which the instruction-pointer should be looked up.
For a look-up in the local address-space,
\Var{unw\_local\_addr\_space} can be passed for this argument.
Argument \Var{ip} is the instruction-pointer for which the procedure
info should be looked up and \Var{pip} is a pointer to a structure of
type \Type{unw\_proc\_info\_t} which is used to return the info.
Lastly, \Var{arg} is the address-space argument that should be used
when accessing the address-space. It has the same purpose as the
argument of the same name for \Func{unw\_init\_remote}(). When
accessing the local address-space (first argument is
\Var{unw\_local\_addr\_space}), \Const{NULL} must be passed for this
argument.
Note that for the purposes of \Prog{libunwind}, the code of a
procedure is assumed to occupy a single, contiguous range of
addresses. For this reason, it is alwas possible to describe the
extent of a procedure with the \Var{start\_ip} and \Var{end\_ip}
members. If a single function/routine is split into multiple,
discontiguous pieces, \Prog{libunwind} will treat each piece as a
separate procedure.
\section{Return Value}
On successful completion, \Func{unw\_get\_proc\_info\_by\_ip}()
returns 0. Otherwise the negative value of one of the error-codes
below is returned.
\section{Thread and Signal Safety}
\Func{unw\_get\_proc\_info}() is thread-safe. If the local
address-space is passed in argument \Var{as}, this routine is also
safe to use from a signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to locate
unwind-info for the procedure.
\item[\Const{UNW\_EBADVERSION}] The unwind-info for the procedure has
version or format that is not understood by \Prog{libunwind}.
\end{Description}
In addition, \Func{unw\_get\_proc\_info}() may return any error
returned by the \Func{access\_mem}() call-back (see
\Func{unw\_create\_addr\_space}(3)).
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_create\_addr\_space(3)},
\SeeAlso{unw\_get\_proc\_name(3)},
\SeeAlso{unw\_get\_proc\_info(3)},
\SeeAlso{unw\_init\_remote(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

123
sdk/cpprt/linux/libunwind/doc/unw_get_proc_name.man Normal file
View File

@ -0,0 +1,123 @@
'\" 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\\_GET\\_PROC\\_NAME" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_get_proc_name
\-\- get name of current procedure
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_get_proc_name(unw_cursor_t *cp,
char *bufp,
size_t
len,
unw_word_t *offp);
.br
.PP
.SH DESCRIPTION
.PP
The unw_get_proc_name()
routine returns the name of the
procedure that created the stack frame identified by argument
cp\&.
The bufp
argument is a pointer to a character buffer
that is at least len
bytes long. This buffer is used to return
the name of the procedure. The offp
argument is a pointer to a
word that is used to return the byte\-offset of the instruction\-pointer
saved in the stack frame identified by cp,
relative to the start
of the procedure. For example, if procedure foo()
starts at
address 0x40003000, then invoking unw_get_proc_name()
on a
stack frame with an instruction\-pointer value of 0x40003080 would
return a value of 0x80 in the word pointed to by offp
(assuming
the procedure is at least 0x80 bytes long).
.PP
Note that on some platforms there is no reliable way to distinguish
between procedure names and ordinary labels. Furthermore, if symbol
information has been stripped from a program, procedure names may be
completely unavailable or may be limited to those exported via a
dynamic symbol table. In such cases, unw_get_proc_name()
may return the name of a label or a preceeding (nearby) procedure.
However, the offset returned through offp
is always relative to
the returned name, which ensures that the value (address) of the
returned name plus the returned offset will always be equal to the
instruction\-pointer of the stack frame identified by cp\&.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_get_proc_name()
returns 0.
Otherwise the negative value of one of the error\-codes below is
returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_get_proc_name()
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_ENOINFO
Libunwind
was unable to determine
the name of the procedure.
.TP
UNW_ENOMME
The procedure name is too long to fit
in the buffer provided. A truncated version of the name has been
returned.
.PP
In addition, unw_get_proc_name()
may return any error
returned by the access_mem()
call\-back (see
unw_create_addr_space(3)).
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_get_proc_info(3)
.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.

82
sdk/cpprt/linux/libunwind/doc/unw_get_proc_name.tex Normal file
View File

@ -0,0 +1,82 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_get\_proc\_name}{David Mosberger-Tang}{Programming Library}{unw\_get\_proc\_name}unw\_get\_proc\_name -- get name of current procedure
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_get\_proc\_name}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{char~*}\Var{bufp}, \Type{size\_t} \Var{len}, \Type{unw\_word\_t~*}\Var{offp});\\
\section{Description}
The \Func{unw\_get\_proc\_name}() routine returns the name of the
procedure that created the stack frame identified by argument
\Var{cp}. The \Var{bufp} argument is a pointer to a character buffer
that is at least \Var{len} bytes long. This buffer is used to return
the name of the procedure. The \Var{offp} argument is a pointer to a
word that is used to return the byte-offset of the instruction-pointer
saved in the stack frame identified by \Var{cp}, relative to the start
of the procedure. For example, if procedure \Func{foo}() starts at
address 0x40003000, then invoking \Func{unw\_get\_proc\_name}() on a
stack frame with an instruction-pointer value of 0x40003080 would
return a value of 0x80 in the word pointed to by \Var{offp} (assuming
the procedure is at least 0x80 bytes long).
Note that on some platforms there is no reliable way to distinguish
between procedure names and ordinary labels. Furthermore, if symbol
information has been stripped from a program, procedure names may be
completely unavailable or may be limited to those exported via a
dynamic symbol table. In such cases, \Func{unw\_get\_proc\_name}()
may return the name of a label or a preceeding (nearby) procedure.
However, the offset returned through \Var{offp} is always relative to
the returned name, which ensures that the value (address) of the
returned name plus the returned offset will always be equal to the
instruction-pointer of the stack frame identified by \Var{cp}.
\section{Return Value}
On successful completion, \Func{unw\_get\_proc\_name}() returns 0.
Otherwise the negative value of one of the error-codes below is
returned.
\section{Thread and Signal Safety}
\Func{unw\_get\_proc\_name}() is thread-safe. If cursor \Var{cp} is
in the local address-space, this routine is also safe to use from a
signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to determine
the name of the procedure.
\item[\Const{UNW\_ENOMME}] The procedure name is too long to fit
in the buffer provided. A truncated version of the name has been
returned.
\end{Description}
In addition, \Func{unw\_get\_proc\_name}() may return any error
returned by the \Func{access\_mem}() call-back (see
\Func{unw\_create\_addr\_space}(3)).
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_get\_proc\_info(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

112
sdk/cpprt/linux/libunwind/doc/unw_get_reg.man Normal file
View File

@ -0,0 +1,112 @@
'\" 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\\_GET\\_REG" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_get_reg
\-\- get register contents
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_get_reg(unw_cursor_t *cp,
unw_regnum_t
reg,
unw_word_t *valp);
.br
.PP
.SH DESCRIPTION
.PP
The unw_get_reg()
routine reads the value of register
reg
in the stack frame identified by cursor cp
and stores
the value in the word pointed to by valp\&.
.PP
The register numbering is target\-dependent and described in separate
manual pages (e.g., libunwind\-ia64(3) for the IA\-64 target).
Furthermore, the exact set of accessible registers may depend on the
type of frame that cp
is referring to. For ordinary stack
frames, it is normally possible to access only the preserved
(``callee\-saved\&'') registers and frame\-related registers (such as the
stack\-pointer). However, for signal frames (see
unw_is_signal_frame(3)),
it is usually possible to access
all registers.
.PP
Note that unw_get_reg()
can only read the contents of
registers whose values fit in a single word. See
unw_get_fpreg(3)
for a way to read registers which do not fit
this constraint.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_get_reg()
returns 0.
Otherwise the negative value of one of the error\-codes below is
returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_get_reg()
is thread\-safe as well as safe to use
from a signal handler.
.PP
.SH ERRORS
.PP
.TP
UNW_EUNSPEC
An unspecified error occurred.
.TP
UNW_EBADREG
An attempt was made to read a register
that is either invalid or not accessible in the current frame.
.PP
In addition, unw_get_reg()
may return any error returned by
the access_mem(),
access_reg(),
and
access_fpreg()
call\-backs (see
unw_create_addr_space(3)).
.PP
.SH SEE ALSO
.PP
libunwind(3),
libunwind\-ia64(3),
unw_get_fpreg(3),
unw_is_signal_frame(3),
unw_set_reg(3)
.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.

77
sdk/cpprt/linux/libunwind/doc/unw_get_reg.tex Normal file
View File

@ -0,0 +1,77 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_get\_reg}{David Mosberger-Tang}{Programming Library}{unw\_get\_reg}unw\_get\_reg -- get register contents
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_get\_reg}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{unw\_regnum\_t} \Var{reg}, \Type{unw\_word\_t~*}\Var{valp});\\
\section{Description}
The \Func{unw\_get\_reg}() routine reads the value of register
\Var{reg} in the stack frame identified by cursor \Var{cp} and stores
the value in the word pointed to by \Var{valp}.
The register numbering is target-dependent and described in separate
manual pages (e.g., libunwind-ia64(3) for the IA-64 target).
Furthermore, the exact set of accessible registers may depend on the
type of frame that \Var{cp} is referring to. For ordinary stack
frames, it is normally possible to access only the preserved
(``callee-saved'') registers and frame-related registers (such as the
stack-pointer). However, for signal frames (see
\Func{unw\_is\_signal\_frame}(3)), it is usually possible to access
all registers.
Note that \Func{unw\_get\_reg}() can only read the contents of
registers whose values fit in a single word. See
\Func{unw\_get\_fpreg}(3) for a way to read registers which do not fit
this constraint.
\section{Return Value}
On successful completion, \Func{unw\_get\_reg}() returns 0.
Otherwise the negative value of one of the error-codes below is
returned.
\section{Thread and Signal Safety}
\Func{unw\_get\_reg}() is thread-safe as well as safe to use
from a signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item[\Const{UNW\_EBADREG}] An attempt was made to read a register
that is either invalid or not accessible in the current frame.
\end{Description}
In addition, \Func{unw\_get\_reg}() may return any error returned by
the \Func{access\_mem}(), \Func{access\_reg}(), and
\Func{access\_fpreg}() call-backs (see
\Func{unw\_create\_addr\_space}(3)).
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{libunwind-ia64(3)},
\SeeAlso{unw\_get\_fpreg(3)},
\SeeAlso{unw\_is\_signal\_frame(3)},
\SeeAlso{unw\_set\_reg(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

93
sdk/cpprt/linux/libunwind/doc/unw_getcontext.man Normal file
View File

@ -0,0 +1,93 @@
'\" 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\\_GETCONTEXT" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_getcontext
\-\- get initial machine\-state
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_getcontext(unw_context_t *ucp);
.br
.PP
.SH DESCRIPTION
.PP
The unw_getcontext()
routine initializes the context structure
pointed to by ucp
with the machine\-state of the call\-site. The
exact set of registers stored by unw_getcontext()
is
platform\-specific, but, in general, at least all preserved
(``callee\-saved\&'') and all frame\-related registers, such as the
stack\-pointer, will be stored.
.PP
This routine is normally implemented as a macro and applications
should not attempt to take its address.
.PP
.SH PLATFORM\-SPECIFIC NOTES
.PP
On IA\-64, unw_context_t
has a layout that is compatible with
that of ucontext_t
and such structures can be initialized with
getcontext()
instead of unw_getcontext().
However, the
reverse is \fInot\fP
true and it is \fInot\fP
safe to use structures
initialized by unw_getcontext()
in places where a structure
initialized by getcontext()
is expected. The reason for this
asymmetry is that unw_getcontext()
is optimized for maximum
performance and does not, for example, save the signal mask.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_getcontext()
returns 0.
Otherwise, a value of \-1 is returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_getcontext()
is thread\-safe as well as safe to use
from a signal handler.
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_init_local(3)
.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.

63
sdk/cpprt/linux/libunwind/doc/unw_getcontext.tex Normal file
View File

@ -0,0 +1,63 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_getcontext}{David Mosberger-Tang}{Programming Library}{unw\_getcontext}unw\_getcontext -- get initial machine-state
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_getcontext}(\Type{unw\_context\_t~*}\Var{ucp});\\
\section{Description}
The \Func{unw\_getcontext}() routine initializes the context structure
pointed to by \Var{ucp} with the machine-state of the call-site. The
exact set of registers stored by \Func{unw\_getcontext}() is
platform-specific, but, in general, at least all preserved
(``callee-saved'') and all frame-related registers, such as the
stack-pointer, will be stored.
This routine is normally implemented as a macro and applications
should not attempt to take its address.
\section{Platform-specific Notes}
On IA-64, \Type{unw\_context\_t} has a layout that is compatible with
that of \Type{ucontext\_t} and such structures can be initialized with
\Func{getcontext}() instead of \Func{unw\_getcontext}(). However, the
reverse is \emph{not} true and it is \emph{not} safe to use structures
initialized by \Func{unw\_getcontext()} in places where a structure
initialized by \Func{getcontext()} is expected. The reason for this
asymmetry is that \Func{unw\_getcontext()} is optimized for maximum
performance and does not, for example, save the signal mask.
\section{Return Value}
On successful completion, \Func{unw\_getcontext}() returns 0.
Otherwise, a value of -1 is returned.
\section{Thread and Signal Safety}
\Func{unw\_getcontext}() is thread-safe as well as safe to use
from a signal handler.
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_init\_local(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

119
sdk/cpprt/linux/libunwind/doc/unw_init_local.man Normal file
View File

@ -0,0 +1,119 @@
'\" 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\\_INIT\\_LOCAL" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_init_local
\-\- initialize cursor for local unwinding
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_init_local(unw_cursor_t *c,
unw_context_t *ctxt);
.br
.PP
.SH DESCRIPTION
.PP
The unw_init_local()
routine initializes the unwind cursor
pointed to by c
with the machine\-state in the context structure
pointed to by ctxt\&.
As such, the machine\-state pointed to by
ctxt
identifies the initial stack frame at which unwinding
starts. The machine\-state must remain valid for the duration for
which the cursor c
is in use.
.PP
The unw_init_local()
routine can be used only for unwinding in
the address space of the current process (i.e., for local unwinding).
For all other cases, unw_init_remote()
must be used instead.
From a behavioral point of view, the call:
.PP
.Vb
ret = unw_init_local(&cursor, &ucontext);
.Ve
is equivalent to:
.PP
.Vb
ret = unw_init_remote(&cursor, unw_local_addr_space,
&ucontext);
.Ve
However, unwind performance may be better when using
unw_init_local().
Also, unw_init_local()
is
available even when UNW_LOCAL_ONLY
has been defined before
including <libunwind.h>,
whereas unw_init_remote()
is not.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_init_local()
returns 0.
Otherwise the negative value of one of the error\-codes below is
returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_init_local()
is thread\-safe as well as safe to use from a
signal handler.
.PP
.SH ERRORS
.PP
.TP
UNW_EINVAL
unw_init_local()
was called in a
version of libunwind
which supports remote unwinding only
(this normally happens when calling unw_init_local()
for a
cross\-platform version of libunwind).
.TP
UNW_EUNSPEC
An unspecified error occurred.
.TP
UNW_EBADREG
A register needed by unw_init_local()
wasn\&'t accessible.
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_init_remote(3)
.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.

81
sdk/cpprt/linux/libunwind/doc/unw_init_local.tex Normal file
View File

@ -0,0 +1,81 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_init\_local}{David Mosberger-Tang}{Programming Library}{unw\_init\_local}unw\_init\_local -- initialize cursor for local unwinding
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_init\_local}(\Type{unw\_cursor\_t~*}\Var{c}, \Type{unw\_context\_t~*}\Var{ctxt});\\
\section{Description}
The \Func{unw\_init\_local}() routine initializes the unwind cursor
pointed to by \Var{c} with the machine-state in the context structure
pointed to by \Var{ctxt}. As such, the machine-state pointed to by
\Var{ctxt} identifies the initial stack frame at which unwinding
starts. The machine-state must remain valid for the duration for
which the cursor \Var{c} is in use.
The \Func{unw\_init\_local}() routine can be used only for unwinding in
the address space of the current process (i.e., for local unwinding).
For all other cases, \Func{unw\_init\_remote}() must be used instead.
From a behavioral point of view, the call:
\begin{verbatim}
ret = unw_init_local(&cursor, &ucontext);
\end{verbatim}
is equivalent to:
\begin{verbatim}
ret = unw_init_remote(&cursor, unw_local_addr_space,
&ucontext);
\end{verbatim}
However, unwind performance may be better when using
\Func{unw\_init\_local}(). Also, \Func{unw\_init\_local}() is
available even when \Const{UNW\_LOCAL\_ONLY} has been defined before
including \File{$<$libunwind.h$>$}, whereas \Func{unw\_init\_remote}()
is not.
\section{Return Value}
On successful completion, \Func{unw\_init\_local}() returns 0.
Otherwise the negative value of one of the error-codes below is
returned.
\section{Thread and Signal Safety}
\Func{unw\_init\_local}() is thread-safe as well as safe to use from a
signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_EINVAL}] \Func{unw\_init\_local}() was called in a
version of \Prog{libunwind} which supports remote unwinding only
(this normally happens when calling \Func{unw\_init\_local}() for a
cross-platform version of \Prog{libunwind}).
\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item[\Const{UNW\_EBADREG}] A register needed by \Func{unw\_init\_local}()
wasn't accessible.
\end{Description}
\section{See Also}
\SeeAlso{libunwind(3)}, \SeeAlso{unw\_init\_remote(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

123
sdk/cpprt/linux/libunwind/doc/unw_init_remote.man Normal file
View File

@ -0,0 +1,123 @@
'\" 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\\_INIT\\_REMOTE" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_init_remote
\-\- initialize cursor for remote unwinding
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_init_remote(unw_cursor_t *c,
unw_addr_space_t as,
void *arg);
.br
.PP
.SH DESCRIPTION
.PP
The unw_init_remote()
routine initializes the unwind cursor
pointed to by c
for unwinding in the address space identified by
as\&.
The as
argument can either be set to
unw_local_addr_space
(local address space) or to an arbitrary
address space created with unw_create_addr_space().
.PP
The arg
void\-pointer tells the address space exactly what entity
should be unwound. For example, if unw_local_addr_space
is
passed in as,
then arg
needs to be a pointer to a context
structure containing the machine\-state of the initial stack frame.
However, other address\-spaces may instead expect a process\-id, a
thread\-id, or a pointer to an arbitrary structure which identifies the
stack\-frame chain to be unwound. In other words, the interpretation
of arg
is entirely dependent on the address\-space in use;
libunwind
never interprets the argument in any way on its own.
.PP
Note that unw_init_remote()
can be used to initiate unwinding
in \fIany\fP
process, including the local process in which the
unwinder itself is running. However, for local unwinding, it is
generally preferable to use unw_init_local()
instead, because
it is easier to use and because it may perform better.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_init_remote()
returns 0.
Otherwise the negative value of one of the error\-codes below is
returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_init_remote()
is thread\-safe. If the local address\-space
is passed in argument as,
this routine is also safe to use from
a signal handler.
.PP
.SH ERRORS
.PP
.TP
UNW_EINVAL
unw_init_remote()
was called in a
version of libunwind
which supports local unwinding only
(this normally happens when defining UNW_LOCAL_ONLY
before
including <libunwind.h>
and then calling
unw_init_remote()).
.TP
UNW_EUNSPEC
An unspecified error occurred.
.TP
UNW_EBADREG
A register needed by unw_init_remote()
wasn\&'t accessible.
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_create_addr_space(3),
unw_init_local(3)
.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.

79
sdk/cpprt/linux/libunwind/doc/unw_init_remote.tex Normal file
View File

@ -0,0 +1,79 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_init\_remote}{David Mosberger-Tang}{Programming Library}{unw\_init\_remote}unw\_init\_remote -- initialize cursor for remote unwinding
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_init\_remote}(\Type{unw\_cursor\_t~*}\Var{c}, \Type{unw\_addr\_space\_t~}\Var{as}, \Type{void~*}\Var{arg});\\
\section{Description}
The \Func{unw\_init\_remote}() routine initializes the unwind cursor
pointed to by \Var{c} for unwinding in the address space identified by
\Var{as}. The \Var{as} argument can either be set to
\Var{unw\_local\_addr\_space} (local address space) or to an arbitrary
address space created with \Func{unw\_create\_addr\_space}().
The \Var{arg} void-pointer tells the address space exactly what entity
should be unwound. For example, if \Var{unw\_local\_addr\_space} is
passed in \Var{as}, then \Var{arg} needs to be a pointer to a context
structure containing the machine-state of the initial stack frame.
However, other address-spaces may instead expect a process-id, a
thread-id, or a pointer to an arbitrary structure which identifies the
stack-frame chain to be unwound. In other words, the interpretation
of \Var{arg} is entirely dependent on the address-space in use;
\Prog{libunwind} never interprets the argument in any way on its own.
Note that \Func{unw\_init\_remote}() can be used to initiate unwinding
in \emph{any} process, including the local process in which the
unwinder itself is running. However, for local unwinding, it is
generally preferable to use \Func{unw\_init\_local}() instead, because
it is easier to use and because it may perform better.
\section{Return Value}
On successful completion, \Func{unw\_init\_remote}() returns 0.
Otherwise the negative value of one of the error-codes below is
returned.
\section{Thread and Signal Safety}
\Func{unw\_init\_remote}() is thread-safe. If the local address-space
is passed in argument \Var{as}, this routine is also safe to use from
a signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_EINVAL}] \Func{unw\_init\_remote}() was called in a
version of \Prog{libunwind} which supports local unwinding only
(this normally happens when defining \Const{UNW\_LOCAL\_ONLY} before
including \File{$<$libunwind.h$>$} and then calling
\Func{unw\_init\_remote}()).
\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item[\Const{UNW\_EBADREG}] A register needed by \Func{unw\_init\_remote}()
wasn't accessible.
\end{Description}
\section{See Also}
\SeeAlso{libunwind(3)}, \SeeAlso{unw\_create\_addr\_space(3)},
\SeeAlso{unw\_init\_local(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

73
sdk/cpprt/linux/libunwind/doc/unw_is_fpreg.man Normal file
View File

@ -0,0 +1,73 @@
'\" 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\\_IS\\_FPREG" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_is_fpreg
\-\- check if a register is a floating\-point register
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_is_fpreg(unw_regnum_t
reg);
.br
.PP
.SH DESCRIPTION
.PP
The unw_is_fpreg()
routine checks whether register number
reg
is a floating\-point register.
.PP
This routine is normally implemented as a macro and applications
should not attempt to take its address.
.PP
.SH RETURN VALUE
.PP
The unw_is_fpreg()
routine returns a non\-zero value if
reg
is a floating\-point register. Otherwise, it returns a value
of 0.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_is_fpreg()
is thread\-safe as well as safe to use
from a signal handler.
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_get_reg(3),
unw_set_reg(3),
unw_get_fpreg(3),
unw_set_fpreg(3)
.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.

52
sdk/cpprt/linux/libunwind/doc/unw_is_fpreg.tex Normal file
View File

@ -0,0 +1,52 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_is\_fpreg}{David Mosberger-Tang}{Programming Library}{unw\_is\_fpreg}unw\_is\_fpreg -- check if a register is a floating-point register
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_is\_fpreg}(\Type{unw\_regnum\_t} \Var{reg});\\
\section{Description}
The \Func{unw\_is\_fpreg}() routine checks whether register number
\Var{reg} is a floating-point register.
This routine is normally implemented as a macro and applications
should not attempt to take its address.
\section{Return Value}
The \Func{unw\_is\_fpreg}() routine returns a non-zero value if
\Var{reg} is a floating-point register. Otherwise, it returns a value
of 0.
\section{Thread and Signal Safety}
\Func{unw\_is\_fpreg}() is thread-safe as well as safe to use
from a signal handler.
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_get\_reg(3)},
\SeeAlso{unw\_set\_reg(3)},
\SeeAlso{unw\_get\_fpreg(3)},
\SeeAlso{unw\_set\_fpreg(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

88
sdk/cpprt/linux/libunwind/doc/unw_is_signal_frame.man Normal file
View File

@ -0,0 +1,88 @@
'\" 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\\_IS\\_SIGNAL\\_FRAME" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_is_signal_frame
\-\- check if current frame is a signal frame
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_is_signal_frame(unw_cursor_t *cp);
.br
.PP
.SH DESCRIPTION
.PP
The unw_is_signal_frame()
routine returns a positive value
if the current frame identified by cp
is a signal frame, and a
value of 0 otherwise. For the purpose of this discussion, a signal
frame is a frame that was created in response to a potentially
asynchronous interruption. For UNIX and UNIX\-like platforms, such
frames are normally created by the kernel when delivering a signal.
In a kernel\-environment, a signal frame might, for example, correspond
to a frame created in response to a device interrupt.
.PP
Signal frames are somewhat unusual because the asynchronous nature of
the events that create them require storing the contents of registers
that are normally treated as scratch (``caller\-saved\&'') registers.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_is_signal_frame()
returns a
positive value if the current frame is a signal frame, or 0 if it is
not. Otherwise, a negative value of one of the error\-codes below is
returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_is_signal_frame()
is thread\-safe as well as safe to use
from a signal handler.
.PP
.SH ERRORS
.PP
.TP
UNW_ENOINFO
Libunwind
is unable to determine
whether or not the current frame is a signal frame.
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_get_reg(3),
unw_set_reg(3),
unw_get_fpreg(3),
unw_set_fpreg(3)
.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.

67
sdk/cpprt/linux/libunwind/doc/unw_is_signal_frame.tex Normal file
View File

@ -0,0 +1,67 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_is\_signal\_frame}{David Mosberger-Tang}{Programming Library}{unw\_is\_signal\_frame}unw\_is\_signal\_frame -- check if current frame is a signal frame
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_is\_signal\_frame}(\Type{unw\_cursor\_t~*}\Var{cp});\\
\section{Description}
The \Func{unw\_is\_signal\_frame}() routine returns a positive value
if the current frame identified by \Var{cp} is a signal frame, and a
value of 0 otherwise. For the purpose of this discussion, a signal
frame is a frame that was created in response to a potentially
asynchronous interruption. For UNIX and UNIX-like platforms, such
frames are normally created by the kernel when delivering a signal.
In a kernel-environment, a signal frame might, for example, correspond
to a frame created in response to a device interrupt.
Signal frames are somewhat unusual because the asynchronous nature of
the events that create them require storing the contents of registers
that are normally treated as scratch (``caller-saved'') registers.
\section{Return Value}
On successful completion, \Func{unw\_is\_signal\_frame}() returns a
positive value if the current frame is a signal frame, or 0 if it is
not. Otherwise, a negative value of one of the error-codes below is
returned.
\section{Thread and Signal Safety}
\Func{unw\_is\_signal\_frame}() is thread-safe as well as safe to use
from a signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} is unable to determine
whether or not the current frame is a signal frame.
\end{Description}
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_get\_reg(3)},
\SeeAlso{unw\_set\_reg(3)},
\SeeAlso{unw\_get\_fpreg(3)},
\SeeAlso{unw\_set\_fpreg(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

68
sdk/cpprt/linux/libunwind/doc/unw_regname.man Normal file
View File

@ -0,0 +1,68 @@
'\" 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\\_REGNAME" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_regname
\-\- get register name
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
const char *unw_regname(unw_regnum_t
regnum);
.br
.PP
.SH DESCRIPTION
.PP
The unw_regname()
routine returns a printable name for
register regnum\&.
If regnum
is an invalid or otherwise
unrecognized register number, a string consisting of three question
marks is returned. The returned string is statically allocated and
therefore guaranteed to remain valid until the application terminates.
.PP
.SH RETURN VALUE
.PP
The unw_regname()
routine cannot fail and always returns a
valid (non\-NULL)
string.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
The unw_regname()
routine is thread\-safe as well as safe to
use from a signal handler.
.PP
.SH SEE ALSO
.PP
libunwind(3)
.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.

47
sdk/cpprt/linux/libunwind/doc/unw_regname.tex Normal file
View File

@ -0,0 +1,47 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_regname}{David Mosberger-Tang}{Programming Library}{unw\_regname}unw\_regname -- get register name
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{const char~*}\Func{unw\_regname}(\Type{unw\_regnum\_t} \Var{regnum});\\
\section{Description}
The \Func{unw\_regname}() routine returns a printable name for
register \Var{regnum}. If \Var{regnum} is an invalid or otherwise
unrecognized register number, a string consisting of three question
marks is returned. The returned string is statically allocated and
therefore guaranteed to remain valid until the application terminates.
\section{Return Value}
The \Func{unw\_regname}() routine cannot fail and always returns a
valid (non-\Const{NULL}) string.
\section{Thread and Signal Safety}
The \Func{unw\_regname}() routine is thread-safe as well as safe to
use from a signal handler.
\section{See Also}
\SeeAlso{libunwind(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

146
sdk/cpprt/linux/libunwind/doc/unw_resume.man Normal file
View File

@ -0,0 +1,146 @@
'\" 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.

99
sdk/cpprt/linux/libunwind/doc/unw_resume.tex Normal file
View File

@ -0,0 +1,99 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_resume}{David Mosberger-Tang}{Programming Library}{unw\_resume}unw\_resume -- resume execution in a particular stack frame
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_resume}(\Type{unw\_cursor\_t~*}\Var{cp});\\
\section{Description}
The \Func{unw\_resume}() routine resumes execution at the stack frame
identified by \Var{cp}. The behavior of this routine differs
slightly for local and remote unwinding.
For local unwinding, \Func{unw\_resume}() restores the machine state
and then directly resumes execution in the target stack frame. Thus
\Func{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
\Var{cp} was interrupted by a signal, then \Func{unw\_resume}() will
restore all registers as well as the signal mask. Attempting to call
\Func{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, \Func{unw\_resume}() installs the machine state
identified by the cursor by calling the \Func{access\_reg} and
\Func{access\_fpreg} accessor callbacks as needed. Once that is
accomplished, the \Func{resume} accessor callback is invoked. The
\Func{unw\_resume} routine then returns normally (that is, unlikely
for local unwinding, \Func{unw\_resume} will always return for remote
unwinding).
Most platforms reserve some registers to pass arguments to exception
handlers (e.g., IA-64 uses \texttt{r15}-\texttt{r18} for this
purpose). These registers are normally treated like ``scratch''
registers. However, if \Prog{libunwind} is used to set an exception
argument register to a particular value (e.g., via
\Func{unw\_set\_reg}()), then \Func{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 \Func{unw\_resume}() does \emph{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 \Type{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).
\section{Return Value}
For local unwinding, \Func{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.
\section{Thread and Signal Safety}
\Func{unw\_resume}() is thread-safe. If cursor \Var{cp} is in the
local address-space, this routine is also safe to use from a signal
handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item[\Const{UNW\_EBADREG}] A register needed by \Func{unw\_resume}() wasn't
accessible.
\item[\Const{UNW\_EINVALIDIP}] The instruction pointer identified by
\Var{cp} is not valid.
\item[\Const{UNW\_BADFRAME}] The stack frame identified by
\Var{cp} is not valid.
\end{Description}
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_set\_reg(3)},
sigprocmask(2)
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

118
sdk/cpprt/linux/libunwind/doc/unw_set_caching_policy.man Normal file
View File

@ -0,0 +1,118 @@
'\" 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\\_SET\\_CACHING\\_POLICY" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_set_caching_policy
\-\- set unwind caching policy
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_set_caching_policy(unw_addr_space_t
as,
unw_caching_policy_t
policy);
.br
.PP
.SH DESCRIPTION
.PP
The unw_set_caching_policy()
routine sets the caching policy
of address space as
to the policy specified by argument
policy\&.
The policy
argument can take one of three
possible values:
.TP
UNW_CACHE_NONE
Turns off caching completely. This
also implicitly flushes the contents of all caches as if
unw_flush_cache()
had been called.
.TP
UNW_CACHE_GLOBAL
Enables caching using a global cache
that is shared by all threads. If global caching is unavailable or
unsupported, libunwind
may fall back on using a per\-thread
cache, as if UNW_CACHE_PER_THREAD
had been specified.
.TP
UNW_CACHE_PER_THREAD
Enables caching using
thread\-local caches. If a thread\-local caching are unavailable or
unsupported, libunwind
may fall back on using a global cache,
as if UNW_CACHE_GLOBAL
had been specified.
.PP
If caching is enabled, an application must be prepared to make
appropriate calls to unw_flush_cache()
whenever the target
changes in a way that could affect the validity of cached information.
For example, after unloading (removing) a shared library,
unw_flush_cache()
would have to be called (at least) for the
address\-range that was covered by the shared library.
.PP
For address spaces created via unw_create_addr_space(3),
caching is turned off by default. For the local address space
unw_local_addr_space,
caching is turned on by default.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_set_caching_policy()
returns 0.
Otherwise the negative value of one of the error\-codes below is
returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_set_caching_policy()
is thread\-safe but \fInot\fP
safe
to use from a signal handler.
.PP
.SH ERRORS
.PP
.TP
UNW_ENOMEM
The desired caching policy could not be
established because the application is out of memory.
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_create_addr_space(3),
unw_flush_cache(3)
.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.

80
sdk/cpprt/linux/libunwind/doc/unw_set_caching_policy.tex Normal file
View File

@ -0,0 +1,80 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_set\_caching\_policy}{David Mosberger-Tang}{Programming Library}{unw\_set\_caching\_policy}unw\_set\_caching\_policy -- set unwind caching policy
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_set\_caching\_policy}(\Type{unw\_addr\_space\_t} \Var{as}, \Type{unw\_caching\_policy\_t} \Var{policy});\\
\section{Description}
The \Func{unw\_set\_caching\_policy}() routine sets the caching policy
of address space \Var{as} to the policy specified by argument
\Var{policy}. The \Var{policy} argument can take one of three
possible values:
\begin{description}
\item[\Const{UNW\_CACHE\_NONE}] Turns off caching completely. This
also implicitly flushes the contents of all caches as if
\Func{unw\_flush\_cache}() had been called.
\item[\Const{UNW\_CACHE\_GLOBAL}] Enables caching using a global cache
that is shared by all threads. If global caching is unavailable or
unsupported, \Prog{libunwind} may fall back on using a per-thread
cache, as if \Const{UNW\_CACHE\_PER\_THREAD} had been specified.
\item[\Const{UNW\_CACHE\_PER\_THREAD}] Enables caching using
thread-local caches. If a thread-local caching are unavailable or
unsupported, \Prog{libunwind} may fall back on using a global cache,
as if \Const{UNW\_CACHE\_GLOBAL} had been specified.
\end{description}
If caching is enabled, an application must be prepared to make
appropriate calls to \Func{unw\_flush\_cache}() whenever the target
changes in a way that could affect the validity of cached information.
For example, after unloading (removing) a shared library,
\Func{unw\_flush\_cache}() would have to be called (at least) for the
address-range that was covered by the shared library.
For address spaces created via \Func{unw\_create\_addr\_space}(3),
caching is turned off by default. For the local address space
\Func{unw\_local\_addr\_space}, caching is turned on by default.
\section{Return Value}
On successful completion, \Func{unw\_set\_caching\_policy}() returns 0.
Otherwise the negative value of one of the error-codes below is
returned.
\section{Thread and Signal Safety}
\Func{unw\_set\_caching\_policy}() is thread-safe but \emph{not} safe
to use from a signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_ENOMEM}] The desired caching policy could not be
established because the application is out of memory.
\end{Description}
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_create\_addr\_space(3)},
\SeeAlso{unw\_flush\_cache(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

117
sdk/cpprt/linux/libunwind/doc/unw_set_fpreg.man Normal file
View File

@ -0,0 +1,117 @@
'\" 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\\_SET\\_FPREG" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_set_fpreg
\-\- set contents of floating\-point register
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_set_fpreg(unw_cursor_t *cp,
unw_regnum_t
reg,
unw_fpreg_t
val);
.br
.PP
.SH DESCRIPTION
.PP
The unw_set_fpreg()
routine sets the value of register
reg
in the stack frame identified by cursor cp
to the
value passed in val\&.
.PP
The register numbering is target\-dependent and described in separate
manual pages (e.g., libunwind\-ia64(3) for the IA\-64 target).
Furthermore, the exact set of accessible registers may depend on the
type of frame that cp
is referring to. For ordinary stack
frames, it is normally possible to access only the preserved
(``callee\-saved\&'') registers and frame\-related registers (such as the
stack\-pointer). However, for signal frames (see
unw_is_signal_frame(3)),
it is usually possible to access
all registers.
.PP
Note that unw_set_fpreg()
can only write the contents of
floating\-point registers. See unw_set_reg(3)
for a way to
write registers which fit in a single word.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_set_fpreg()
returns 0.
Otherwise the negative value of one of the error\-codes below is
returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_set_fpreg()
is thread\-safe as well as safe to use
from a signal handler.
.PP
.SH ERRORS
.PP
.TP
UNW_EUNSPEC
An unspecified error occurred.
.TP
UNW_EBADREG
An attempt was made to write a register
that is either invalid or not accessible in the current frame.
.TP
UNW_EREADONLY
An attempt was made to write to a
read\-only register.
.PP
In addition, unw_set_fpreg()
may return any error returned by
the access_mem(),
access_reg(),
and
access_fpreg()
call\-backs (see
unw_create_addr_space(3)).
.PP
.SH SEE ALSO
.PP
libunwind(3),
libunwind\-ia64(3),
unw_get_fpreg(3),
unw_is_fpreg(3),
unw_is_signal_frame(3),
unw_set_reg(3)
.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.

79
sdk/cpprt/linux/libunwind/doc/unw_set_fpreg.tex Normal file
View File

@ -0,0 +1,79 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_set\_fpreg}{David Mosberger-Tang}{Programming Library}{unw\_set\_fpreg}unw\_set\_fpreg -- set contents of floating-point register
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_set\_fpreg}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{unw\_regnum\_t} \Var{reg}, \Type{unw\_fpreg\_t} \Var{val});\\
\section{Description}
The \Func{unw\_set\_fpreg}() routine sets the value of register
\Var{reg} in the stack frame identified by cursor \Var{cp} to the
value passed in \Var{val}.
The register numbering is target-dependent and described in separate
manual pages (e.g., libunwind-ia64(3) for the IA-64 target).
Furthermore, the exact set of accessible registers may depend on the
type of frame that \Var{cp} is referring to. For ordinary stack
frames, it is normally possible to access only the preserved
(``callee-saved'') registers and frame-related registers (such as the
stack-pointer). However, for signal frames (see
\Func{unw\_is\_signal\_frame}(3)), it is usually possible to access
all registers.
Note that \Func{unw\_set\_fpreg}() can only write the contents of
floating-point registers. See \Func{unw\_set\_reg}(3) for a way to
write registers which fit in a single word.
\section{Return Value}
On successful completion, \Func{unw\_set\_fpreg}() returns 0.
Otherwise the negative value of one of the error-codes below is
returned.
\section{Thread and Signal Safety}
\Func{unw\_set\_fpreg}() is thread-safe as well as safe to use
from a signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item[\Const{UNW\_EBADREG}] An attempt was made to write a register
that is either invalid or not accessible in the current frame.
\item[\Const{UNW\_EREADONLY}] An attempt was made to write to a
read-only register.
\end{Description}
In addition, \Func{unw\_set\_fpreg}() may return any error returned by
the \Func{access\_mem}(), \Func{access\_reg}(), and
\Func{access\_fpreg}() call-backs (see
\Func{unw\_create\_addr\_space}(3)).
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{libunwind-ia64(3)},
\SeeAlso{unw\_get\_fpreg(3)},
\SeeAlso{unw\_is\_fpreg(3)},
\SeeAlso{unw\_is\_signal\_frame(3)},
\SeeAlso{unw\_set\_reg(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

117
sdk/cpprt/linux/libunwind/doc/unw_set_reg.man Normal file
View File

@ -0,0 +1,117 @@
'\" 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\\_SET\\_REG" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_set_reg
\-\- set register contents
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_set_reg(unw_cursor_t *cp,
unw_regnum_t
reg,
unw_word_t
val);
.br
.PP
.SH DESCRIPTION
.PP
The unw_set_reg()
routine sets the value of register
reg
in the stack frame identified by cursor cp
to the
value passed in val\&.
.PP
The register numbering is target\-dependent and described in separate
manual pages (e.g., libunwind\-ia64(3) for the IA\-64 target).
Furthermore, the exact set of accessible registers may depend on the
type of frame that cp
is referring to. For ordinary stack
frames, it is normally possible to access only the preserved
(``callee\-saved\&'') registers and frame\-related registers (such as the
stack\-pointer). However, for signal frames (see
unw_is_signal_frame(3)),
it is usually possible to access
all registers.
.PP
Note that unw_set_reg()
can only write the contents of
registers whose values fit in a single word. See
unw_set_fpreg(3)
for a way to write registers which do not
fit this constraint.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_set_reg()
returns 0.
Otherwise the negative value of one of the error\-codes below is
returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_set_reg()
is thread\-safe as well as safe to use
from a signal handler.
.PP
.SH ERRORS
.PP
.TP
UNW_EUNSPEC
An unspecified error occurred.
.TP
UNW_EBADREG
An attempt was made to write a register
that is either invalid or not accessible in the current frame.
.TP
UNW_EREADONLY
An attempt was made to write to a
read\-only register.
.PP
In addition, unw_set_reg()
may return any error returned by
the access_mem(),
access_reg(),
and
access_fpreg()
call\-backs (see
unw_create_addr_space(3)).
.PP
.SH SEE ALSO
.PP
libunwind(3),
libunwind\-ia64(3),
unw_get_reg(3),
unw_is_signal_frame(3),
unw_set_fpreg(3)
.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.

79
sdk/cpprt/linux/libunwind/doc/unw_set_reg.tex Normal file
View File

@ -0,0 +1,79 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_set\_reg}{David Mosberger-Tang}{Programming Library}{unw\_set\_reg}unw\_set\_reg -- set register contents
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_set\_reg}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{unw\_regnum\_t} \Var{reg}, \Type{unw\_word\_t} \Var{val});\\
\section{Description}
The \Func{unw\_set\_reg}() routine sets the value of register
\Var{reg} in the stack frame identified by cursor \Var{cp} to the
value passed in \Var{val}.
The register numbering is target-dependent and described in separate
manual pages (e.g., libunwind-ia64(3) for the IA-64 target).
Furthermore, the exact set of accessible registers may depend on the
type of frame that \Var{cp} is referring to. For ordinary stack
frames, it is normally possible to access only the preserved
(``callee-saved'') registers and frame-related registers (such as the
stack-pointer). However, for signal frames (see
\Func{unw\_is\_signal\_frame}(3)), it is usually possible to access
all registers.
Note that \Func{unw\_set\_reg}() can only write the contents of
registers whose values fit in a single word. See
\Func{unw\_set\_fpreg}(3) for a way to write registers which do not
fit this constraint.
\section{Return Value}
On successful completion, \Func{unw\_set\_reg}() returns 0.
Otherwise the negative value of one of the error-codes below is
returned.
\section{Thread and Signal Safety}
\Func{unw\_set\_reg}() is thread-safe as well as safe to use
from a signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item[\Const{UNW\_EBADREG}] An attempt was made to write a register
that is either invalid or not accessible in the current frame.
\item[\Const{UNW\_EREADONLY}] An attempt was made to write to a
read-only register.
\end{Description}
In addition, \Func{unw\_set\_reg}() may return any error returned by
the \Func{access\_mem}(), \Func{access\_reg}(), and
\Func{access\_fpreg}() call-backs (see
\Func{unw\_create\_addr\_space}(3)).
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{libunwind-ia64(3)},
\SeeAlso{unw\_get\_reg(3)},
\SeeAlso{unw\_is\_signal\_frame(3)},
\SeeAlso{unw\_set\_fpreg(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

106
sdk/cpprt/linux/libunwind/doc/unw_step.man Normal file
View File

@ -0,0 +1,106 @@
'\" 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\\_STEP" "3" "16 August 2007" "Programming Library " "Programming Library "
.SH NAME
unw_step
\-\- advance to next stack frame
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
int
unw_step(unw_cursor_t *cp);
.br
.PP
.SH DESCRIPTION
.PP
The unw_step()
routine advances the unwind cursor cp
to
the next older, less deeply nested stack frame.
.PP
.SH RETURN VALUE
.PP
On successful completion, unw_step()
returns a positive value
if the updated cursor refers to a valid stack frame, or 0 if the
previous stack frame was the last frame in the chain. On error, the
negative value of one of the error\-codes below is returned.
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_step()
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_ENOINFO
Libunwind
was unable to locate the
unwind\-info needed to complete the operation.
.TP
UNW_EBADVERSION
The unwind\-info needed to complete the
operation has a version or a format that is not understood by
libunwind\&.
.TP
UNW_EINVALIDIP
The instruction\-pointer
(``program\-counter\&'') of the next stack frame is invalid (e.g., not
properly aligned).
.TP
UNW_EBADFRAME
The next stack frame is invalid.
.TP
UNW_ESTOPUNWIND
Returned if a call to
find_proc_info()
returned \-UNW_ESTOPUNWIND\&.
.PP
In addition, unw_step()
may return any error returned by the
find_proc_info(),
get_dyn_info_list_addr(),
access_mem(),
access_reg(),
or access_fpreg()
call\-backs (see unw_create_addr_space(3)).
.PP
.SH SEE ALSO
.PP
libunwind(3),
unw_create_addr_space(3)
.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.

68
sdk/cpprt/linux/libunwind/doc/unw_step.tex Normal file
View File

@ -0,0 +1,68 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_step}{David Mosberger-Tang}{Programming Library}{unw\_step}unw\_step -- advance to next stack frame
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_step}(\Type{unw\_cursor\_t~*}\Var{cp});\\
\section{Description}
The \Func{unw\_step}() routine advances the unwind cursor \Var{cp} to
the next older, less deeply nested stack frame.
\section{Return Value}
On successful completion, \Func{unw\_step}() returns a positive value
if the updated cursor refers to a valid stack frame, or 0 if the
previous stack frame was the last frame in the chain. On error, the
negative value of one of the error-codes below is returned.
\section{Thread and Signal Safety}
\Func{unw\_step}() is thread-safe. If cursor \Var{cp} is in the local
address-space, this routine is also safe to use from a signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to locate the
unwind-info needed to complete the operation.
\item[\Const{UNW\_EBADVERSION}] The unwind-info needed to complete the
operation has a version or a format that is not understood by
\Prog{libunwind}.
\item[\Const{UNW\_EINVALIDIP}] The instruction-pointer
(``program-counter'') of the next stack frame is invalid (e.g., not
properly aligned).
\item[\Const{UNW\_EBADFRAME}] The next stack frame is invalid.
\item[\Const{UNW\_ESTOPUNWIND}] Returned if a call to
\Func{find\_proc\_info}() returned -\Const{UNW\_ESTOPUNWIND}.
\end{Description}
In addition, \Func{unw\_step}() may return any error returned by the
\Func{find\_proc\_info}(), \Func{get\_dyn\_info\_list\_addr}(),
\Func{access\_mem}(), \Func{access\_reg}(), or \Func{access\_fpreg}()
call-backs (see \Func{unw\_create\_addr\_space}(3)).
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_create\_addr\_space(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}

63
sdk/cpprt/linux/libunwind/doc/unw_strerror.man Normal file
View File

@ -0,0 +1,63 @@
'\" t
.\" Manual page created with latex2man on Wed Aug 18 16:51:29 CEST 2004
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R
.fi
..
.TH "UNW\\_STRERROR" "3" "18 August 2004" "Programming Library " "Programming Library "
.SH NAME
unw_strerror
\-\- get text corresponding to error code
.PP
.SH SYNOPSIS
.PP
#include <libunwind.h>
.br
.PP
const char *
unw_strerror(int
err_code);
.br
.PP
.SH DESCRIPTION
.PP
The unw_strerror()
routine maps the (negative) err_code
to a corresponding text message and returns it.
.PP
.SH RETURN VALUE
.PP
The message that corresponds to err_code
or, if the
err_code
has no corresponding message, the text "invalid error
code".
.PP
.SH THREAD AND SIGNAL SAFETY
.PP
unw_strerror()
is thread\-safe as well as safe to use
from a signal handler.
.PP
.SH AUTHOR
.PP
Thomas Hallgren
.br
BEA Systems
.br
Stockholm, Sweden
.br
Email: \fBthallgre@bea.com\fP
.br
.\" NOTE: This file is generated, DO NOT EDIT.

42
sdk/cpprt/linux/libunwind/doc/unw_strerror.tex Normal file
View File

@ -0,0 +1,42 @@
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_strerror}{Thomas Hallgren}{Programming Library}{unw\_strerror}unw\_strerror -- get text corresponding to error code
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{const char *} \Func{unw\_strerror}(\Type{int} \Var{err\_code});\\
\section{Description}
The \Func{unw\_strerror}() routine maps the (negative) \Var{err\_code}
to a corresponding text message and returns it.
\section{Return Value}
The message that corresponds to \Var{err\_code} or, if the
\Var{err\_code} has no corresponding message, the text "invalid error
code".
\section{Thread and Signal Safety}
\Func{unw\_strerror}() is thread-safe as well as safe to use
from a signal handler.
\section{Author}
\noindent
Thomas Hallgren\\
BEA Systems\\
Stockholm, Sweden\\
Email: \Email{thallgre@bea.com}\\
\LatexManEnd
\end{document}