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 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 24 following 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} 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 82 separate procedure. 83 84 \section{Return Value} 85 86 On successful completion, \Func{unw\_get\_proc\_info}() returns 0. 87 Otherwise the negative value of one of the error-codes below is 88 returned. 89 90 \section{Thread and Signal Safety} 91 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 94 signal 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} 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)). 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 118 David Mosberger-Tang\\ 119 Email: \Email{dmosberger (a] gmail.com}\\ 120 WWW: \URL{http://www.nongnu.org/libunwind/}. 121 \LatexManEnd 122 123 \end{document} 124
