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