unw_create_addr_space - Man Page

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);

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.

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.

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.

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.

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.

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.

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.

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.