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
|
\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}
\input{common.tex}
\begin{document}
\begin{Name}{3}{unw\_get\_proc\_info}{David Mosberger-Tang}{Programming Library}{unw\_get\_proc\_info}unw\_get\_proc\_info -- get info on current procedure
\end{Name}
\section{Synopsis}
\File{\#include $<$libunwind.h$>$}\\
\Type{int} \Func{unw\_get\_proc\_info}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{unw\_proc\_info\_t~*}\Var{pip});\\
\section{Description}
The \Func{unw\_get\_proc\_info}() routine returns auxiliary
information about the procedure that created the stack frame
identified by argument \Var{cp}. The \Var{pip} argument is a pointer
to a structure of type \Type{unw\_proc\_info\_t} which is used to
return the information. The \Type{unw\_proc\_info\_t} has the
following members:
\begin{description}
\item[\Type{unw\_word\_t} \Var{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 \Var{start\_ip}
member is cleared to 0. \\
\item[\Type{unw\_word\_t} \Var{end\_ip}] The address of the first
instruction \emph{beyond} the end of the procedure. If this address
cannot be determined (e.g., due to lack of unwind information),
the \Var{end\_ip} member is cleared to 0. \\
\item[\Type{unw\_word\_t} \Var{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. \\
\item[\Type{unw\_word\_t} \Var{handler}] The address of the exception
handler routine. This is sometimes called the \emph{personality}
routine. If the procedure does not define
a personality routine, the \Var{handler} member is cleared to 0. \\
\item[\Type{unw\_word\_t} \Var{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. \\
\item[\Type{unw\_word\_t} \Var{flags}] A set of flags. There are
currently no target-independent flags. For the IA-64 target, the
flag \Const{UNW\_PI\_FLAG\_IA64\_RBS\_SWITCH} is set if the
procedure may switch the register-backing store.\\
\item[\Type{int} \Var{format}] The format of the unwind-info for this
procedure. If the unwind-info consists of dynamic procedure info,
\Var{format} is equal to \Const{UNW\_INFO\_FORMAT\_DYNAMIC}. If the
unwind-info consists of a (target-specific) unwind table, it is
equal to \Const{UNW\_INFO\_FORMAT\_TABLE}. All other values are
reserved for future use by \Prog{libunwind}. This member exists
for use by the \Func{find\_proc\_info}() call-back (see
\Func{unw\_create\_addr\_space}(3)). The
\Func{unw\_get\_proc\_info}() routine
may return an undefined value in this member. \\
\item[\Type{int} \Var{unwind\_info\_size}] The size of the unwind-info
in bytes. This member exists for use by the
\Func{find\_proc\_info}() call-back (see
\Func{unw\_create\_addr\_space}(3)). The
\Func{unw\_get\_proc\_info}() routine
may return an undefined value in this member.\\
\item[\Type{void~*}\Var{unwind\_info}] The pointer to the unwind-info.
If no unwind info is available, this member must be set to
\Const{NULL}. This member exists for use by the
\Func{find\_proc\_info}() call-back (see
\Func{unw\_create\_addr\_space}(3)). The
\Func{unw\_get\_proc\_info}() routine
may return an undefined value in this member.\\
\end{description}
Note that for the purposes of \Prog{libunwind}, the code of a
procedure is assumed to occupy a single, contiguous range of
addresses. For this reason, it is always possible to describe the
extent of a procedure with the \Var{start\_ip} and \Var{end\_ip}
members. If a single function/routine is split into multiple,
discontiguous pieces, \Prog{libunwind} will treat each piece as a
separate procedure.
\section{Return Value}
On successful completion, \Func{unw\_get\_proc\_info}() returns 0.
Otherwise the negative value of one of the error-codes below is
returned.
\section{Thread and Signal Safety}
\Func{unw\_get\_proc\_info}() is thread-safe. If cursor \Var{cp} is
in the local address-space, this routine is also safe to use from a
signal handler.
\section{Errors}
\begin{Description}
\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
\item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to locate
unwind-info for the procedure.
\item[\Const{UNW\_EBADVERSION}] The unwind-info for the procedure has
version or format that is not understood by \Prog{libunwind}.
\end{Description}
In addition, \Func{unw\_get\_proc\_info}() may return any error
returned by the \Func{access\_mem}() call-back (see
\Func{unw\_create\_addr\_space}(3)).
\section{See Also}
\SeeAlso{libunwind(3)},
\SeeAlso{unw\_create\_addr\_space(3)},
\SeeAlso{unw\_get\_proc\_name(3)}
\section{Author}
\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd
\end{document}
|
