mirror of
https://github.com/tobast/libunwind-eh_elf.git
synced 2024-11-05 17:24:30 +01:00
461 lines
12 KiB
Groff
461 lines
12 KiB
Groff
'\" t
|
|
.\" Manual page created with latex2man on Thu Aug 5 10:20:31 CEST 2004
|
|
.\" NOTE: This file is generated, DO NOT EDIT.
|
|
.de Vb
|
|
.ft CW
|
|
.nf
|
|
..
|
|
.de Ve
|
|
.ft R
|
|
|
|
.fi
|
|
..
|
|
.TH "UNW\\_CREATE\\_ADDR\\_SPACE" "3" "05 August 2004" "Programming Library " "Programming Library "
|
|
.SH NAME
|
|
unw_create_addr_space
|
|
\-\- create address space for remote unwinding
|
|
.PP
|
|
.SH SYNOPSIS
|
|
|
|
.PP
|
|
#include <libunwind.h>
|
|
.br
|
|
.PP
|
|
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. In particular, this
|
|
call\-back may return \-UNW_ESTOPUNWIND
|
|
to signal the end of
|
|
the frame\-chain.
|
|
.PP
|
|
.SS PUT_UNWIND_INFO
|
|
.PP
|
|
Libunwind
|
|
invokes the put_unwind_info()
|
|
call\-back to
|
|
release the resources (such as memory) allocated by a previous call to
|
|
find_proc_info()
|
|
with the need_unwind_info
|
|
argument
|
|
set to a non\-zero value. The pip
|
|
argument has the same value as
|
|
the argument of the same name in the previous matching call to
|
|
find_proc_info().
|
|
Note that libunwind
|
|
does \fInot\fP
|
|
invoke put_unwind_info
|
|
for calls to find_proc_info()
|
|
with a zero need_unwind_info
|
|
argument.
|
|
.PP
|
|
.SS GET_DYN_INFO_LIST_ADDR
|
|
.PP
|
|
Libunwind
|
|
invokes the get_dyn_info_list_addr()
|
|
call\-back to obtain the address of the head of the dynamic unwind\-info
|
|
registration list. The variable stored at the returned address must
|
|
have a type of unw_dyn_info_list_t
|
|
(see
|
|
_U_dyn_register(3)).
|
|
The dliap
|
|
argument is a pointer
|
|
to a variable of type unw_word_t
|
|
which is used to return the
|
|
address of the dynamic unwind\-info registration list. If no dynamic
|
|
unwind\-info registration list exist, the value pointed to by
|
|
dliap
|
|
must be cleared to zero. Libunwind
|
|
will cache the
|
|
value returned by get_dyn_info_list_addr()
|
|
if caching is
|
|
enabled for the given address\-space. The cache can be cleared with a
|
|
call to unw_flush_cache().
|
|
.PP
|
|
On successful completion, the get_dyn_info_list_addr()
|
|
call\-back must return zero. Otherwise, the negative value of one of
|
|
the unw_error_t
|
|
error\-codes may be returned.
|
|
.PP
|
|
.SS ACCESS_MEM
|
|
.PP
|
|
Libunwind
|
|
invokes the access_mem()
|
|
call\-back to read
|
|
from or write to a word of memory in the target address\-space. The
|
|
address of the word to be accessed is passed in argument addr\&.
|
|
To read memory, libunwind
|
|
sets argument write
|
|
to zero and
|
|
valp
|
|
to point to the word that receives the read value. To
|
|
write memory, libunwind
|
|
sets argument write
|
|
to a non\-zero
|
|
value and valp
|
|
to point to the word that contains the value to
|
|
be written. The word that valp
|
|
points to is always in the
|
|
byte\-order of the host\-platform, regardless of the byte\-order of the
|
|
target. In other words, it is the responsibility of the call\-back
|
|
routine to convert between the target\&'s and the host\&'s byte\-order, if
|
|
necessary.
|
|
.PP
|
|
On successful completion, the access_mem()
|
|
call\-back must return zero. Otherwise, the negative value of one of
|
|
the unw_error_t
|
|
error\-codes may be returned.
|
|
.PP
|
|
.SS ACCESS_REG
|
|
.PP
|
|
Libunwind
|
|
invokes the access_reg()
|
|
call\-back to read
|
|
from or write to a scalar (non\-floating\-point) CPU register. The
|
|
index of the register to be accessed is passed in argument
|
|
regnum\&.
|
|
To read a register, libunwind
|
|
sets argument
|
|
write
|
|
to zero and valp
|
|
to point to the word that receives
|
|
the read value. To write a register, libunwind
|
|
sets argument
|
|
write
|
|
to a non\-zero value and valp
|
|
to point to the word
|
|
that contains the value to be written. The word that valp
|
|
points to is always in the byte\-order of the host\-platform, regardless
|
|
of the byte\-order of the target. In other words, it is the
|
|
responsibility of the call\-back routine to convert between the
|
|
target\&'s and the host\&'s byte\-order, if necessary.
|
|
.PP
|
|
On successful completion, the access_reg()
|
|
call\-back must
|
|
return zero. Otherwise, the negative value of one of the
|
|
unw_error_t
|
|
error\-codes may be returned.
|
|
.PP
|
|
.SS ACCESS_FPREG
|
|
.PP
|
|
Libunwind
|
|
invokes the access_fpreg()
|
|
call\-back to read
|
|
from or write to a floating\-point CPU register. The index of the
|
|
register to be accessed is passed in argument regnum\&.
|
|
To read a
|
|
register, libunwind
|
|
sets argument write
|
|
to zero and
|
|
fpvalp
|
|
to point to a variable of type unw_fpreg_t
|
|
that
|
|
receives the read value. To write a register, libunwind
|
|
sets
|
|
argument write
|
|
to a non\-zero value and fpvalp
|
|
to point to
|
|
the variable of type unw_fpreg_t
|
|
that contains the value to
|
|
be written. The word that fpvalp
|
|
points to is always in the
|
|
byte\-order of the host\-platform, regardless of the byte\-order of the
|
|
target. In other words, it is the responsibility of the call\-back
|
|
routine to convert between the target\&'s and the host\&'s byte\-order, if
|
|
necessary.
|
|
.PP
|
|
On successful completion, the access_fpreg()
|
|
call\-back must
|
|
return zero. Otherwise, the negative value of one of the
|
|
unw_error_t
|
|
error\-codes may be returned.
|
|
.PP
|
|
.SS RESUME
|
|
.PP
|
|
Libunwind
|
|
invokes the resume()
|
|
call\-back to resume
|
|
execution in the target address space. Argument cp
|
|
is the
|
|
unwind\-cursor that identifies the stack\-frame in which execution
|
|
should resume. By the time libunwind
|
|
invokes the resume
|
|
call\-back, it has already established the desired machine\- and
|
|
memory\-state via calls to the access_reg(),
|
|
access_fpreg,
|
|
and access_mem()
|
|
call\-backs. Thus, all
|
|
the call\-back needs to do is perform whatever action is needed to
|
|
actually resume execution.
|
|
.PP
|
|
The resume
|
|
call\-back is invoked only in response to a call to
|
|
unw_resume(3),
|
|
so applications which never invoke
|
|
unw_resume(3)
|
|
need not define the resume
|
|
callback.
|
|
.PP
|
|
On successful completion, the resume()
|
|
call\-back must return
|
|
zero. Otherwise, the negative value of one of the
|
|
unw_error_t
|
|
error\-codes may be returned. As a special case,
|
|
when resuming execution in the local address space, the call\-back will
|
|
not return on success.
|
|
.PP
|
|
.SS GET_PROC_NAME
|
|
.PP
|
|
Libunwind
|
|
invokes the get_proc_name()
|
|
call\-back to
|
|
obtain the procedure\-name of a static (not dynamically generated)
|
|
procedure. Argument addr
|
|
is an instruction\-address within the
|
|
procedure whose name is to be obtained. The bufp
|
|
argument is a
|
|
pointer to a character\-buffer used to return the procedure name. The
|
|
size of this buffer is specified in argument buf_len\&.
|
|
The
|
|
returned name must be terminated by a NUL character. If the
|
|
procedure\&'s name is longer than buf_len
|
|
bytes, it must be
|
|
truncated to buf_len\-1
|
|
bytes, with the last byte in the
|
|
buffer set to the NUL character and \-UNW_ENOMEM
|
|
must be
|
|
returned. Argument offp
|
|
is a pointer to a word which is used to
|
|
return the byte\-offset relative to the start of the procedure whose
|
|
name is being returned. For example, if procedure foo()
|
|
starts
|
|
at address 0x40003000, then invoking get_proc_name()
|
|
with
|
|
addr
|
|
set to 0x40003080 should return a value of 0x80 in the word
|
|
pointed to by offp
|
|
(assuming the procedure is at least 0x80
|
|
bytes long).
|
|
.PP
|
|
On successful completion, the get_proc_name()
|
|
call\-back must
|
|
return zero. Otherwise, the negative value of one of the
|
|
unw_error_t
|
|
error\-codes may be returned.
|
|
.PP
|
|
.SH RETURN VALUE
|
|
|
|
.PP
|
|
On successful completion, unw_create_addr_space()
|
|
returns a
|
|
non\-NULL
|
|
value that represents the newly created
|
|
address\-space. Otherwise, NULL
|
|
is returned.
|
|
.PP
|
|
.SH THREAD AND SIGNAL SAFETY
|
|
|
|
.PP
|
|
unw_create_addr_space()
|
|
is thread\-safe but \fInot\fP
|
|
safe to use from a signal handler.
|
|
.PP
|
|
.SH SEE ALSO
|
|
|
|
.PP
|
|
_U_dyn_register(3),
|
|
libunwind(3),
|
|
unw_destroy_addr_space(3),
|
|
unw_get_proc_info(3),
|
|
unw_init_remote(3),
|
|
unw_resume(3)
|
|
.PP
|
|
.SH AUTHOR
|
|
|
|
.PP
|
|
David Mosberger\-Tang
|
|
.br
|
|
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.
|