summaryrefslogtreecommitdiff
path: root/doc/unw_get_proc_info.man
blob: 31bda2b20558dce56f6ec7984ff24fbb859383a2 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
'\" t
.\" Manual page created with latex2man on Thu Aug  5 10:20:31 CEST 2004
.\" NOTE: This file is generated, DO NOT EDIT.
.de Vb
.ft CW
.nf
..
.de Ve
.ft R

.fi
..
.TH "UNW\\_GET\\_PROC\\_INFO" "3" "05 August 2004" "Programming Library " "Programming Library "
.SH NAME
unw_get_proc_info
\-\- get info on current procedure 
.PP
.SH SYNOPSIS

.PP
#include <libunwind.h>
.br
.PP
int
unw_get_proc_info(unw_cursor_t *cp,
unw_proc_info_t *pip);
.br
.PP
.SH DESCRIPTION

.PP
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: 
.TP
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. 
.br 
.TP
unw_word_t end_ip
 The address of the first 
instruction \fIbeyond\fP
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. 
.br 
.TP
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. 
.br 
.TP
unw_word_t handler
 The address of the exception 
handler routine. This is sometimes called the \fIpersonality\fP
routine. If the procedure does not define 
a personality routine, the handler
member is cleared to 0. 
.br 
.TP
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. 
.br 
.TP
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.
.br 
.TP
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. 
.br 
.TP
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.
.br 
.TP
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.
.br 
.PP
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. 
.PP
.SH RETURN VALUE

.PP
On successful completion, unw_get_proc_info()
returns 0. 
Otherwise the negative value of one of the error\-codes below is 
returned. 
.PP
.SH THREAD AND SIGNAL SAFETY

.PP
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. 
.PP
.SH ERRORS

.PP
.TP
UNW_EUNSPEC
 An unspecified error occurred. 
.TP
UNW_ENOINFO
 Libunwind
was unable to locate 
unwind\-info for the procedure. 
.TP
UNW_EBADVERSION
 The unwind\-info for the procedure has 
version or format that is not understood by libunwind\&.
.PP
In addition, unw_get_proc_info()
may return any error 
returned by the access_mem()
call\-back (see 
unw_create_addr_space(3)).
.PP
.SH SEE ALSO

.PP
libunwind(3),
unw_create_addr_space(3),
unw_get_proc_name(3)
.PP
.SH AUTHOR

.PP
David Mosberger\-Tang
.br 
Hewlett\-Packard Labs
.br 
Palo\-Alto, CA 94304
.br 
Email: \fBdavidm@hpl.hp.com\fP
.br
WWW: \fBhttp://www.hpl.hp.com/research/linux/libunwind/\fP\&.
.\" NOTE: This file is generated, DO NOT EDIT.