unw_get_proc_info man page

unw_get_proc_info -- get info on current procedure

Synopsis

#include <libunwind.h>

int unw_get_proc_info(unw_cursor_t *cp, unw_proc_info_t *pip);

Description

The unw_get_proc_info() routine returns auxiliary  information about the procedure that created the stack frame  identified by argument cp. The pip argument is a pointer  to a structure of type unw_proc_info_t which is used to  return the information. The unw_proc_info_t has the  following members:

unw_word_t start_ip

The address of the first  instruction of the procedure. If this address cannot be determined  (e.g., due to lack of unwind information), the start_ip member is cleared to 0.

unw_word_t end_ip

The address of the first  instruction beyond the end of the procedure. If this address  cannot be determined (e.g., due to lack of unwind information),  the end_ip member is cleared to 0.

unw_word_t lsda

The address of the  language-specific data-area (LSDA). This area normally contains  language-specific information needed during exception handling. If  the procedure has no such area, this member is cleared to 0.

unw_word_t handler

The address of the exception  handler routine. This is sometimes called the personality routine. If the procedure does not define  a personality routine, the handler member is cleared to 0.

unw_word_t gp

The global-pointer of the  procedure. On platforms that do not use a global pointer, this  member may contain an undefined value. On all other platforms, it  must be set either to the correct global-pointer value of the  procedure or to 0 if the proper global-pointer cannot be  obtained for some reason.

unw_word_t flags

A set of flags. There are  currently no target-independent flags. For the IA-64 target, the  flag UNW_PI_FLAG_IA64_RBS_SWITCH is set if the  procedure may switch the register-backing store.

int format

The format of the unwind-info for this  procedure. If the unwind-info consists of dynamic procedure info,  format is equal to UNW_INFO_FORMAT_DYNAMIC. If the  unwind-info consists of a (target-specific) unwind table, it is  equal to to UNW_INFO_FORMAT_TABLE. All other values are  reserved for future use by libunwind. This member exists  for use by the find_proc_info() call-back (see  unw_create_addr_space(3)). The  unw_get_proc_info() routine  may return an undefined value in this member.

int unwind_info_size

The size of the unwind-info  in bytes. This member exists for use by the  find_proc_info() call-back (see  unw_create_addr_space(3)). The  unw_get_proc_info() routine  may return an undefined value in this member.

void *unwind_info

The pointer to the unwind-info.  If no unwind info is available, this member must be set to  NULL. This member exists for use by the  find_proc_info() call-back (see  unw_create_addr_space(3)). The  unw_get_proc_info() routine  may return an undefined value in this member.

Note that for the purposes of libunwind, the code of a  procedure is assumed to occupy a single, contiguous range of  addresses. For this reason, it is alwas possible to describe the  extent of a procedure with the start_ip and end_ip members. If a single function/routine is split into multiple,  discontiguous pieces, libunwind will treat each piece as a  separate procedure.

Return Value

On successful completion, unw_get_proc_info() returns 0.  Otherwise the negative value of one of the error-codes below is  returned.

Thread and Signal Safety

unw_get_proc_info() is thread-safe. If cursor cp is  in the local address-space, this routine is also safe to use from a  signal handler.

Errors

UNW_EUNSPEC

An unspecified error occurred.

UNW_ENOINFO

Libunwind was unable to locate  unwind-info for the procedure.

UNW_EBADVERSION

The unwind-info for the procedure has  version or format that is not understood by libunwind.

In addition, unw_get_proc_info() may return any error  returned by the access_mem() call-back (see  unw_create_addr_space(3)).

See Also

libunwind(3), unw_create_addr_space(3), unw_get_proc_name(3)

Author

David Mosberger-Tang
Email: dmosberger@gmail.com
WWW: http://www.nongnu.org/libunwind/.

Referenced By

libunwind(3), unw_create_addr_space(3), unw_get_proc_info_by_ip(3), unw_get_proc_name(3).

16 August 2007 Programming Library