NAME

       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/.