1UNW_GET_PROC_INFO(3)         Programming Library          UNW_GET_PROC_INFO(3)
2
3
4

NAME

6       unw_get_proc_info -- get info on current procedure
7

SYNOPSIS

9       #include <libunwind.h>
10
11       int unw_get_proc_info(unw_cursor_t *cp, unw_proc_info_t *pip);
12

DESCRIPTION

14       The unw_get_proc_info() routine returns auxiliary information about the
15       procedure that created the stack frame identified by argument cp.   The
16       pip  argument is a pointer to a structure of type unw_proc_info_t which
17       is used to return the information. The unw_proc_info_t has the  follow‐
18       ing members:
19
20       unw_word_t start_ip
21               The  address of the first instruction of the procedure. If this
22              address cannot be determined (e.g., due to lack of unwind infor‐
23              mation), the start_ip member is cleared to 0.
24
25       unw_word_t end_ip
26               The address of the first instruction beyond the end of the pro‐
27              cedure. If this address cannot be determined (e.g., due to  lack
28              of unwind information), the end_ip member is cleared to 0.
29
30       unw_word_t lsda
31               The  address  of  the  language-specific data-area (LSDA). This
32              area normally contains language-specific information needed dur‐
33              ing  exception handling. If the procedure has no such area, this
34              member is cleared to 0.
35
36       unw_word_t handler
37               The address of the exception handler routine. This is sometimes
38              called the personality routine. If the procedure does not define
39              a personality routine, the handler member is cleared to 0.
40
41       unw_word_t gp
42               The global-pointer of the procedure. On platforms that  do  not
43              use  a  global  pointer,  this  member  may contain an undefined
44              value. On all other platforms, it must be set either to the cor‐
45              rect global-pointer value of the procedure or to 0 if the proper
46              global-pointer cannot be obtained for some reason.
47
48       unw_word_t flags
49               A set of  flags.  There  are  currently  no  target-independent
50              flags.      For      the      IA-64     target,     the     flag
51              UNW_PI_FLAG_IA64_RBS_SWITCH is set if the procedure  may  switch
52              the register-backing store.
53
54       int format
55               The  format  of  the  unwind-info  for  this  procedure. If the
56              unwind-info consists of dynamic procedure info, format is  equal
57              to  UNW_INFO_FORMAT_DYNAMIC.   If  the unwind-info consists of a
58              (target-specific) unwind table, it is equal to to  UNW_INFO_FOR‐
59              MAT_TABLE.   All  other  values  are  reserved for future use by
60              libunwind.  This member exists for use by  the  find_proc_info()
61              call-back       (see       unw_create_addr_space(3)).        The
62              unw_get_proc_info() routine may return  an  undefined  value  in
63              this member.
64
65       int unwind_info_size
66               The  size  of  the unwind-info in bytes. This member exists for
67              use   by   the   find_proc_info()   call-back   (see    unw_cre‐
68              ate_addr_space(3)).   The unw_get_proc_info() routine may return
69              an undefined value in this member.
70
71       void *unwind_info
72               The pointer to the unwind-info.  If no unwind  info  is  avail‐
73              able,  this  member must be set to NULL.  This member exists for
74              use   by   the   find_proc_info()   call-back   (see    unw_cre‐
75              ate_addr_space(3)).   The unw_get_proc_info() routine may return
76              an undefined value in this member.
77
78       Note that for the purposes of libunwind, the code  of  a  procedure  is
79       assumed  to  occupy  a  single, contiguous range of addresses. For this
80       reason, it is alwas possible to describe the extent of a procedure with
81       the  start_ip and end_ip members. If a single function/routine is split
82       into multiple, discontiguous pieces, libunwind will treat each piece as
83       a separate procedure.
84

RETURN VALUE

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

THREAD AND SIGNAL SAFETY

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

ERRORS

94       UNW_EUNSPEC
95               An unspecified error occurred.
96
97       UNW_ENOINFO
98               Libunwind was unable to locate unwind-info for the procedure.
99
100       UNW_EBADVERSION
101               The unwind-info for the procedure has version or format that is
102              not understood by libunwind.
103
104       In addition, unw_get_proc_info() may return any error returned  by  the
105       access_mem() call-back (see unw_create_addr_space(3)).
106

SEE ALSO

108       libunwind(3), unw_create_addr_space(3), unw_get_proc_name(3)
109

AUTHOR

111       David Mosberger-Tang
112       Hewlett-Packard Labs
113       Palo-Alto, CA 94304
114       Email: davidm@hpl.hp.com
115       WWW: http://www.hpl.hp.com/research/linux/libunwind/.
116
117
118
119Programming Library             05 August 2004            UNW_GET_PROC_INFO(3)
Impressum