DragonFly On-Line Manual Pages

Search: Section:  

UNW_GET_PROC_INFO(3)         Programming Library          UNW_GET_PROC_INFO(3)


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

Programming Library             16 August 2007            UNW_GET_PROC_INFO(3)

Search: Section: