doc/unw_get_proc_info.man

   1 '\" t
   2 .\" Manual page created with latex2man on Thu Aug 16 09:44:44 MDT 2007
   3 .\" NOTE: This file is generated, DO NOT EDIT.
   4 .de Vb
   5 .ft CW
   6 .nf
   7 ..
   8 .de Ve
   9 .ft R
  10
  11 .fi
  12 ..
  13 .TH "UNW\\_GET\\_PROC\\_INFO" "3" "16 August 2007" "Programming Library " "Programming Library "
  14 .SH NAME
  15 unw_get_proc_info
  16 \-\- get info on current procedure
  17 .PP
  18 .SH SYNOPSIS
  19
  20 .PP
  21 #include <libunwind.h>
  22 .br
  23 .PP
  24 int
  25 unw_get_proc_info(unw_cursor_t *cp,
  26 unw_proc_info_t *pip);
  27 .br
  28 .PP
  29 .SH DESCRIPTION
  30
  31 .PP
  32 The unw_get_proc_info()
  33 routine returns auxiliary
  34 information about the procedure that created the stack frame
  35 identified by argument cp\&.
  36 The pip
  37 argument is a pointer
  38 to a structure of type unw_proc_info_t
  39 which is used to
  40 return the information. The unw_proc_info_t
  41 has the
  42 following members:
  43 .TP
  44 unw_word_t start_ip
  45  The address of the first
  46 instruction of the procedure. If this address cannot be determined
  47 (e.g., due to lack of unwind information), the start_ip
  48 member is cleared to 0.
  49 .br
  50 .TP
  51 unw_word_t end_ip
  52  The address of the first
  53 instruction \fIbeyond\fP
  54 the end of the procedure. If this address
  55 cannot be determined (e.g., due to lack of unwind information),
  56 the end_ip
  57 member is cleared to 0.
  58 .br
  59 .TP
  60 unw_word_t lsda
  61  The address of the
  62 language\-specific data\-area (LSDA). This area normally contains
  63 language\-specific information needed during exception handling. If
  64 the procedure has no such area, this member is cleared to 0.
  65 .br
  66 .TP
  67 unw_word_t handler
  68  The address of the exception
  69 handler routine. This is sometimes called the \fIpersonality\fP
  70 routine. If the procedure does not define
  71 a personality routine, the handler
  72 member is cleared to 0.
  73 .br
  74 .TP
  75 unw_word_t gp
  76  The global\-pointer of the
  77 procedure. On platforms that do not use a global pointer, this
  78 member may contain an undefined value. On all other platforms, it
  79 must be set either to the correct global\-pointer value of the
  80 procedure or to 0 if the proper global\-pointer cannot be
  81 obtained for some reason.
  82 .br
  83 .TP
  84 unw_word_t flags
  85  A set of flags. There are
  86 currently no target\-independent flags. For the IA\-64 target, the
  87 flag UNW_PI_FLAG_IA64_RBS_SWITCH
  88 is set if the
  89 procedure may switch the register\-backing store.
  90 .br
  91 .TP
  92 int format
  93  The format of the unwind\-info for this
  94 procedure. If the unwind\-info consists of dynamic procedure info,
  95 format
  96 is equal to UNW_INFO_FORMAT_DYNAMIC\&.
  97 If the
  98 unwind\-info consists of a (target\-specific) unwind table, it is
  99 equal to to UNW_INFO_FORMAT_TABLE\&.
 100 All other values are
 101 reserved for future use by libunwind\&.
 102 This member exists
 103 for use by the find_proc_info()
 104 call\-back (see
 105 unw_create_addr_space(3)).
 106 The
 107 unw_get_proc_info()
 108 routine
 109 may return an undefined value in this member.
 110 .br
 111 .TP
 112 int unwind_info_size
 113  The size of the unwind\-info
 114 in bytes. This member exists for use by the
 115 find_proc_info()
 116 call\-back (see
 117 unw_create_addr_space(3)).
 118 The
 119 unw_get_proc_info()
 120 routine
 121 may return an undefined value in this member.
 122 .br
 123 .TP
 124 void *unwind_info
 125  The pointer to the unwind\-info.
 126 If no unwind info is available, this member must be set to
 127 NULL\&.
 128 This member exists for use by the
 129 find_proc_info()
 130 call\-back (see
 131 unw_create_addr_space(3)).
 132 The
 133 unw_get_proc_info()
 134 routine
 135 may return an undefined value in this member.
 136 .br
 137 .PP
 138 Note that for the purposes of libunwind,
 139 the code of a
 140 procedure is assumed to occupy a single, contiguous range of
 141 addresses. For this reason, it is alwas possible to describe the
 142 extent of a procedure with the start_ip
 143 and end_ip
 144 members. If a single function/routine is split into multiple,
 145 discontiguous pieces, libunwind
 146 will treat each piece as a
 147 separate procedure.
 148 .PP
 149 .SH RETURN VALUE
 150
 151 .PP
 152 On successful completion, unw_get_proc_info()
 153 returns 0.
 154 Otherwise the negative value of one of the error\-codes below is
 155 returned.
 156 .PP
 157 .SH THREAD AND SIGNAL SAFETY
 158
 159 .PP
 160 unw_get_proc_info()
 161 is thread\-safe. If cursor cp
 162 is
 163 in the local address\-space, this routine is also safe to use from a
 164 signal handler.
 165 .PP
 166 .SH ERRORS
 167
 168 .PP
 169 .TP
 170 UNW_EUNSPEC
 171  An unspecified error occurred.
 172 .TP
 173 UNW_ENOINFO
 174  Libunwind
 175 was unable to locate
 176 unwind\-info for the procedure.
 177 .TP
 178 UNW_EBADVERSION
 179  The unwind\-info for the procedure has
 180 version or format that is not understood by libunwind\&.
 181 .PP
 182 In addition, unw_get_proc_info()
 183 may return any error
 184 returned by the access_mem()
 185 call\-back (see
 186 unw_create_addr_space(3)).
 187 .PP
 188 .SH SEE ALSO
 189
 190 .PP
 191 libunwind(3),
 192 unw_create_addr_space(3),
 193 unw_get_proc_name(3)
 194 .PP
 195 .SH AUTHOR
 196
 197 .PP
 198 David Mosberger\-Tang
 199 .br
 200 Email: \fBdmosberger@gmail.com\fP
 201 .br
 202 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 203 .\" NOTE: This file is generated, DO NOT EDIT.