Provided by: libunwind-dev_1.8.1-0.1ubuntu1_amd64 
NAME
unw_create_addr_space -- create address space for remote unwinding
SYNOPSIS
#include <libunwind.h>
unw_addr_space_t unw_create_addr_space(unw_accessors_t *ap, int byteorder);
DESCRIPTION
The unw_create_addr_space() routine creates a new unwind address space and initializes it based on the
callback routines passed via the ap pointer and the specified byteorder. The callback 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, UNW_LITTLE_ENDIAN would request little-endian byte order and UNW_BIG_ENDIAN would request
big-endian byte order. Whether or not a particular byte order is supported depends on the target
platform.
CALLBACK ROUTINES
Libunwind uses a set of callback 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().
The first argument to every callback routine is an address space identifier (as) and the last argument is
an arbitrary, application specified void pointer (arg). When invoking a callback 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(3libunwind) was called.
The synopsis and a detailed description of every callback routine follows below.
CALLBACK ROUTINE SYNOPSIS
int find_proc_info(unw_addr_space_t as,
unw_word_t ip, unw_proc_info_t *pip,
int need_unwind_info, void *arg);
void put_unwind_info(unw_addr_space_t as,
unw_proc_info_t *pip, void *arg);
int get_dyn_info_list_addr(unw_addr_space_t as,
unw_word_t *dilap, void *arg);
int access_mem(unw_addr_space_t as,
unw_word_t addr, unw_word_t *valp,
int write, void *arg);
int access_reg(unw_addr_space_t as,
unw_regnum_t regnum, unw_word_t *valp,
int write, void *arg);
int access_fpreg(unw_addr_space_t as,
unw_regnum_t regnum, unw_fpreg_t *fpvalp,
int write, void *arg);
int resume(unw_addr_space_t as,
unw_cursor_t *cp, void *arg);
int get_proc_name(unw_addr_space_t as,
unw_word_t addr, char *bufp,
size_t buf_len, unw_word_t *offp,
void *arg);
FIND_PROC_INFO
Libunwind invokes the find_proc_info() callback 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(3libunwind) for details. Argument need_unwind_info is
zero if the callback 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 callback (see below).
On successful completion, the find_proc_info() callback must return zero. Otherwise, the negative value
of one of the unw_error_t error codes may be returned. In particular, this callback may return
-UNW_ESTOPUNWIND to signal the end of the frame chain.
PUT_UNWIND_INFO
Libunwind invokes the put_unwind_info() callback 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 not invoke put_unwind_info for calls to find_proc_info() with
a zero need_unwind_info argument.
GET_DYN_INFO_LIST_ADDR
Libunwind invokes the get_dyn_info_list_addr() callback 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(3libunwind)). 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().
On successful completion, the get_dyn_info_list_addr() callback must return zero. Otherwise, the negative
value of one of the unw_error_t error codes may be returned.
ACCESS_MEM
Libunwind invokes the access_mem() callback 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
callback routine to convert between the target's and the host's byte order, if necessary.
On successful completion, the access_mem() callback must return zero. Otherwise, the negative value of
one of the unw_error_t error codes may be returned.
ACCESS_REG
Libunwind invokes the access_reg() callback 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
callback routine to convert between the target's and the host's byte order, if necessary.
On successful completion, the access_reg() callback must return zero. Otherwise, the negative value of
one of the unw_error_t error codes may be returned.
ACCESS_FPREG
Libunwind invokes the access_fpreg() callback 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 callback routine to convert between the target's and the host's
byte order, if necessary.
On successful completion, the access_fpreg() callback must return zero. Otherwise, the negative value of
one of the unw_error_t error codes may be returned.
RESUME
Libunwind invokes the resume() callback 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 callback, it has already established the desired machine and memory state via calls to
the access_reg(), access_fpreg, and access_mem() callbacks. Thus, all the callback needs to do is perform
whatever action is needed to actually resume execution.
The resume callback is invoked only in response to a call to unw_resume(3libunwind), so applications
which never invoke unw_resume(3libunwind) need not define the resume callback.
On successful completion, the resume() callback 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 callback will not return on success.
GET_PROC_NAME
Libunwind invokes the get_proc_name() callback 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).
On successful completion, the get_proc_name() callback must return zero. Otherwise, the negative value of
one of the unw_error_t error codes may be returned.
RETURN VALUE
On successful completion, unw_create_addr_space() returns a non-NULL value that represents the newly
created address space. Otherwise, NULL is returned.
THREAD AND SIGNAL SAFETY
unw_create_addr_space() is thread-safe but not safe to use from a signal handler.
SEE ALSO
_U_dyn_register(3libunwind), libunwind(3libunwind), unw_destroy_addr_space(3libunwind),
unw_get_proc_info(3libunwind), unw_init_remote(3libunwind), unw_resume(3libunwind)
AUTHOR
David Mosberger-Tang
Email: dmosberger@gmail.com
WWW: http://www.nongnu.org/libunwind/.
Programming Library 29 August 2023 UNW_CREATE_ADDR_SPACE(3libunwind)