mirror of
https://github.com/tobast/libunwind-eh_elf.git
synced 2024-06-02 01:12:37 +02:00
(Logical change 1.60)
This commit is contained in:
mostang.com!davidm
parent
0f0eb30d78
commit
40fe9d4459
460
doc/unw_create_addr_space.man
Normal file
460
doc/unw_create_addr_space.man
Normal file
|
|
@ -0,0 +1,460 @@
|
|||
'\" t
|
||||
.\" Manual page created with latex2man on Mon Mar 10 17:00:59 PST 2003
|
||||
.\" NOTE: This file is generated, DO NOT EDIT.
|
||||
.de Vb
|
||||
.ft CW
|
||||
.nf
|
||||
..
|
||||
.de Ve
|
||||
.ft R
|
||||
|
||||
.fi
|
||||
..
|
||||
.TH "UNW\\_CREATE\\_ADDR\\_SPACE" "3" "10 March 2003" "Programming Library " "Programming Library "
|
||||
.SH NAME
|
||||
|
||||
.PP
|
||||
unw_create_addr_space \-\- create address space for remote unwinding
|
||||
.PP
|
||||
.SH SYNOPSIS
|
||||
|
||||
.PP
|
||||
#include <libunwind.h>
|
||||
.br
|
||||
.PP
|
||||
int
|
||||
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.
|
||||
.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. Otherwise, the last byte in the
|
||||
buffer must be set to a non\-NUL character. This makes it possible to
|
||||
quickly test whether the name may have been truncated by testing the
|
||||
whether the last byte in the buffer is NUL. 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
|
||||
Hewlett\-Packard Labs
|
||||
.br
|
||||
Palo\-Alto, CA 94304
|
||||
.br
|
||||
Email: \fBdavidm@hpl.hp.com\fP
|
||||
.br
|
||||
WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&.
|
||||
.\" NOTE: This file is generated, DO NOT EDIT.
|
||||
271
doc/unw_create_addr_space.tex
Normal file
271
doc/unw_create_addr_space.tex
Normal file
|
|
@ -0,0 +1,271 @@
|
|||
\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{int} \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.
|
||||
|
||||
\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. Otherwise, the last byte in the
|
||||
buffer must be set to a non-NUL character. This makes it possible to
|
||||
quickly test whether the name may have been truncated by testing the
|
||||
whether the last byte in the buffer is NUL. 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.
|
||||
|
||||
\end{Description}
|
||||
|
||||
\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\\
|
||||
Hewlett-Packard Labs\\
|
||||
Palo-Alto, CA 94304\\
|
||||
Email: \Email{davidm@hpl.hp.com}\\
|
||||
WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
|
||||
\LatexManEnd
|
||||
|
||||
\end{document}
|
||||
57
doc/unw_destroy_addr_space.man
Normal file
57
doc/unw_destroy_addr_space.man
Normal file
|
|
@ -0,0 +1,57 @@
|
|||
'\" t
|
||||
.\" Manual page created with latex2man on Mon Mar 10 17:01:00 PST 2003
|
||||
.\" NOTE: This file is generated, DO NOT EDIT.
|
||||
.de Vb
|
||||
.ft CW
|
||||
.nf
|
||||
..
|
||||
.de Ve
|
||||
.ft R
|
||||
|
||||
.fi
|
||||
..
|
||||
.TH "UNW\\_DESTROY\\_ADDR\\_SPACE" "3" "10 March 2003" "Programming Library " "Programming Library "
|
||||
.SH NAME
|
||||
|
||||
.PP
|
||||
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
|
||||
.SH SEE ALSO
|
||||
|
||||
.PP
|
||||
libunwind(3),
|
||||
unw_create_addr_space(3)
|
||||
.PP
|
||||
.SH AUTHOR
|
||||
|
||||
.PP
|
||||
David Mosberger\-Tang
|
||||
.br
|
||||
Hewlett\-Packard Labs
|
||||
.br
|
||||
Palo\-Alto, CA 94304
|
||||
.br
|
||||
Email: \fBdavidm@hpl.hp.com\fP
|
||||
.br
|
||||
WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&.
|
||||
.\" NOTE: This file is generated, DO NOT EDIT.
|
||||
42
doc/unw_destroy_addr_space.tex
Normal file
42
doc/unw_destroy_addr_space.tex
Normal file
|
|
@ -0,0 +1,42 @@
|
|||
\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).
|
||||
|
||||
\end{Description}
|
||||
|
||||
\section{See Also}
|
||||
|
||||
\SeeAlso{libunwind(3)},
|
||||
\SeeAlso{unw\_create\_addr\_space(3)}
|
||||
|
||||
\section{Author}
|
||||
|
||||
\noindent
|
||||
David Mosberger-Tang\\
|
||||
Hewlett-Packard Labs\\
|
||||
Palo-Alto, CA 94304\\
|
||||
Email: \Email{davidm@hpl.hp.com}\\
|
||||
WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
|
||||
\LatexManEnd
|
||||
|
||||
\end{document}
|
||||
124
doc/unw_init_local.man
Normal file
124
doc/unw_init_local.man
Normal file
|
|
@ -0,0 +1,124 @@
|
|||
'\" t
|
||||
.\" Manual page created with latex2man on Fri Mar 7 14:50:51 PST 2003
|
||||
.\" NOTE: This file is generated, DO NOT EDIT.
|
||||
.de Vb
|
||||
.ft CW
|
||||
.nf
|
||||
..
|
||||
.de Ve
|
||||
.ft R
|
||||
|
||||
.fi
|
||||
..
|
||||
.TH "UNW\\_INIT\\_LOCAL" "3" "07 March 2003" "Programming Library " "Programming Library "
|
||||
.SH NAME
|
||||
|
||||
.PP
|
||||
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
|
||||
Hewlett\-Packard Labs
|
||||
.br
|
||||
Palo\-Alto, CA 94304
|
||||
.br
|
||||
Email: \fBdavidm@hpl.hp.com\fP
|
||||
.br
|
||||
WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&.
|
||||
.\" NOTE: This file is generated, DO NOT EDIT.
|
||||
85
doc/unw_init_local.tex
Normal file
85
doc/unw_init_local.tex
Normal file
|
|
@ -0,0 +1,85 @@
|
|||
\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\\
|
||||
Hewlett-Packard Labs\\
|
||||
Palo-Alto, CA 94304\\
|
||||
Email: \Email{davidm@hpl.hp.com}\\
|
||||
WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
|
||||
\LatexManEnd
|
||||
|
||||
\end{document}
|
||||
126
doc/unw_init_remote.man
Normal file
126
doc/unw_init_remote.man
Normal file
|
|
@ -0,0 +1,126 @@
|
|||
'\" t
|
||||
.\" Manual page created with latex2man on Fri Mar 7 15:35:52 PST 2003
|
||||
.\" NOTE: This file is generated, DO NOT EDIT.
|
||||
.de Vb
|
||||
.ft CW
|
||||
.nf
|
||||
..
|
||||
.de Ve
|
||||
.ft R
|
||||
|
||||
.fi
|
||||
..
|
||||
.TH "UNW\\_INIT\\_REMOTE" "3" "07 March 2003" "Programming Library " "Programming Library "
|
||||
.SH NAME
|
||||
|
||||
.PP
|
||||
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 as well as 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
|
||||
Hewlett\-Packard Labs
|
||||
.br
|
||||
Palo\-Alto, CA 94304
|
||||
.br
|
||||
Email: \fBdavidm@hpl.hp.com\fP
|
||||
.br
|
||||
WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&.
|
||||
.\" NOTE: This file is generated, DO NOT EDIT.
|
||||
82
doc/unw_init_remote.tex
Normal file
82
doc/unw_init_remote.tex
Normal file
|
|
@ -0,0 +1,82 @@
|
|||
\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 as well as 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\\
|
||||
Hewlett-Packard Labs\\
|
||||
Palo-Alto, CA 94304\\
|
||||
Email: \Email{davidm@hpl.hp.com}\\
|
||||
WWW: \URL{http://www.hpl.hp.com/research/linux/libunwind/}.
|
||||
\LatexManEnd
|
||||
|
||||
\end{document}
|
||||
Loading…
Reference in a new issue