1 \documentclass{article}
2 \usepackage[fancyhdr,pdf]{latex2man}
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
13 \File{\#include $<$libunwind.h$>$}\\
15 \Type{int} \Func{unw\_get\_proc\_info}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{unw\_proc\_info\_t~*}\Var{pip});\\
19 The \Func{unw\_get\_proc\_info}() routine returns auxiliary
20 information about the procedure that created the stack frame
21 identified by argument \Var{cp}. The \Var{pip} argument is a pointer
22 to a structure of type \Type{unw\_proc\_info\_t} which is used to
23 return the information. The \Type{unw\_proc\_info\_t} has the
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.\\
76 Note that for the purposes of \Prog{libunwind}, the code of a
77 procedure is assumed to occupy a single, contiguous range of
78 addresses. For this reason, it is alwas possible to describe the
79 extent of a procedure with the \Var{start\_ip} and \Var{end\_ip}
80 members. If a single function/routine is split into multiple,
81 discontiguous pieces, \Prog{libunwind} will treat each piece as a
84 \section{Return Value}
86 On successful completion, \Func{unw\_get\_proc\_info}() returns 0.
87 Otherwise the negative value of one of the error-codes below is
90 \section{Thread and Signal Safety}
92 \Func{unw\_get\_proc\_info}() is thread-safe. If cursor \Var{cp} is
93 in the local address-space, this routine is also safe to use from a
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}.
105 In addition, \Func{unw\_get\_proc\_info}() may return any error
106 returned by the \Func{access\_mem}() call-back (see
107 \Func{unw\_create\_addr\_space}(3)).
111 \SeeAlso{libunwind(3)},
112 \SeeAlso{unw\_create\_addr\_space(3)},
113 \SeeAlso{unw\_get\_proc\_name(3)}
118 David Mosberger-Tang\\
119 Email: \Email{dmosberger@gmail.com}\\
120 WWW: \URL{http://www.nongnu.org/libunwind/}.