1
0
Fork 0
mirror of https://github.com/tobast/libunwind-eh_elf.git synced 2024-12-23 03:53:43 +01:00
libunwind-eh_elf/doc/unw_create_addr_space.man
2007-08-22 12:49:08 -06:00

457 lines
12 KiB
Groff

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