mirror of
https://github.com/tobast/libunwind-eh_elf.git
synced 2025-01-25 17:50:29 +01:00
Initial revision
This commit is contained in:
mostang.com!davidm
parent
a494d61a86
commit
cc297605d4
8 changed files with 0 additions and 1247 deletions
|
|
@ -1,460 +0,0 @@
|
||||||
'\" 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.
|
|
||||||
|
|
@ -1,271 +0,0 @@
|
||||||
\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}
|
|
||||||
|
|
@ -1,57 +0,0 @@
|
||||||
'\" 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.
|
|
||||||
|
|
@ -1,42 +0,0 @@
|
||||||
\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}
|
|
||||||
|
|
@ -1,124 +0,0 @@
|
||||||
'\" 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.
|
|
||||||
|
|
@ -1,85 +0,0 @@
|
||||||
\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}
|
|
||||||
|
|
@ -1,126 +0,0 @@
|
||||||
'\" 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.
|
|
||||||
|
|
@ -1,82 +0,0 @@
|
||||||
\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