1\documentclass{article}
2\usepackage[fancyhdr,pdf]{latex2man}
3
4\input{common.tex}
5
6\begin{document}
7
8\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
9\end{Name}
10
11\section{Synopsis}
12
13\File{\#include $<$libunwind.h$>$}\\
14
15\Type{int} \Func{unw\_get\_proc\_info}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{unw\_proc\_info\_t~*}\Var{pip});\\
16
17\section{Description}
18
19The \Func{unw\_get\_proc\_info}() routine returns auxiliary
20information about the procedure that created the stack frame
21identified by argument \Var{cp}.  The \Var{pip} argument is a pointer
22to a structure of type \Type{unw\_proc\_info\_t} which is used to
23return the information.  The \Type{unw\_proc\_info\_t} has the
24following members:
25\begin{description}
26\item[\Type{unw\_word\_t} \Var{start\_ip}] The address of the first
27  instruction of the procedure.  If this address cannot be determined
28  (e.g., due to lack of unwind information), the \Var{start\_ip}
29  member is cleared to 0.  \\
30\item[\Type{unw\_word\_t} \Var{end\_ip}] The address of the first
31  instruction \emph{beyond} the end of the procedure.  If this address
32  cannot be determined (e.g., due to lack of unwind information),
33  the \Var{end\_ip} member is cleared to 0.  \\
34\item[\Type{unw\_word\_t} \Var{lsda}] The address of the
35  language-specific data-area (LSDA).  This area normally contains
36  language-specific information needed during exception handling.  If
37  the procedure has no such area, this member is cleared to 0.  \\
38\item[\Type{unw\_word\_t} \Var{handler}] The address of the exception
39  handler routine.  This is sometimes called the \emph{personality}
40  routine.  If the procedure does not define
41  a personality routine, the \Var{handler} member is cleared to 0.  \\
42\item[\Type{unw\_word\_t} \Var{gp}] The global-pointer of the
43  procedure.  On platforms that do not use a global pointer, this
44  member may contain an undefined value.  On all other platforms, it
45  must be set either to the correct global-pointer value of the
46  procedure or to 0 if the proper global-pointer cannot be
47  obtained for some reason.  \\
48\item[\Type{unw\_word\_t} \Var{flags}] A set of flags.  There are
49  currently no target-independent flags.  For the IA-64 target, the
50  flag \Const{UNW\_PI\_FLAG\_IA64\_RBS\_SWITCH} is set if the
51  procedure may switch the register-backing store.\\
52\item[\Type{int} \Var{format}] The format of the unwind-info for this
53  procedure.  If the unwind-info consists of dynamic procedure info,
54  \Var{format} is equal to \Const{UNW\_INFO\_FORMAT\_DYNAMIC}.  If the
55  unwind-info consists of a (target-specific) unwind table, it is
56  equal to to \Const{UNW\_INFO\_FORMAT\_TABLE}.  All other values are
57  reserved for future use by \Prog{libunwind}.  This member exists
58  for use by the \Func{find\_proc\_info}() call-back (see
59  \Func{unw\_create\_addr\_space}(3)).  The
60  \Func{unw\_get\_proc\_info}() routine
61  may return an undefined value in this member. \\
62\item[\Type{int} \Var{unwind\_info\_size}] The size of the unwind-info
63  in bytes.  This member exists for use by the
64  \Func{find\_proc\_info}() call-back (see
65  \Func{unw\_create\_addr\_space}(3)).  The
66  \Func{unw\_get\_proc\_info}() routine
67  may return an undefined value in this member.\\
68\item[\Type{void~*}\Var{unwind\_info}] The pointer to the unwind-info.
69  If no unwind info is available, this member must be set to
70  \Const{NULL}.  This member exists for use by the
71  \Func{find\_proc\_info}() call-back (see
72  \Func{unw\_create\_addr\_space}(3)).  The
73  \Func{unw\_get\_proc\_info}() routine
74  may return an undefined value in this member.\\
75\end{description}
76Note that for the purposes of \Prog{libunwind}, the code of a
77procedure is assumed to occupy a single, contiguous range of
78addresses.  For this reason, it is alwas possible to describe the
79extent of a procedure with the \Var{start\_ip} and \Var{end\_ip}
80members.  If a single function/routine is split into multiple,
81discontiguous pieces, \Prog{libunwind} will treat each piece as a
82separate procedure.
83
84\section{Return Value}
85
86On successful completion, \Func{unw\_get\_proc\_info}() returns 0.
87Otherwise the negative value of one of the error-codes below is
88returned.
89
90\section{Thread and Signal Safety}
91
92\Func{unw\_get\_proc\_info}() is thread-safe.  If cursor \Var{cp} is
93in the local address-space, this routine is also safe to use from a
94signal handler.
95
96\section{Errors}
97
98\begin{Description}
99\item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
100\item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to locate
101  unwind-info for the procedure.
102\item[\Const{UNW\_EBADVERSION}] The unwind-info for the procedure has
103  version or format that is not understood by \Prog{libunwind}.
104\end{Description}
105In addition, \Func{unw\_get\_proc\_info}() may return any error
106returned by the \Func{access\_mem}() call-back (see
107\Func{unw\_create\_addr\_space}(3)).
108
109\section{See Also}
110
111\SeeAlso{libunwind(3)},
112\SeeAlso{unw\_create\_addr\_space(3)},
113\SeeAlso{unw\_get\_proc\_name(3)}
114
115\section{Author}
116
117\noindent
118David Mosberger-Tang\\
119Email: \Email{dmosberger@gmail.com}\\
120WWW: \URL{http://www.nongnu.org/libunwind/}.
121\LatexManEnd
122
123\end{document}
124