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\_by\_ip}{David Mosberger-Tang}{Programming Library}{unw\_get\_proc\_info\_by\_ip}unw\_get\_proc\_info\_by\_ip -- get procedure info by IP 9 \end{Name} 10 11 \section{Synopsis} 12 13 \File{\#include $<$libunwind.h$>$}\\ 14 15 \Type{int} \Func{unw\_get\_proc\_info\_by\_ip}(\Type{unw\_addr\_space\_t~}\Var{as}, \Type{unw\_word\_t~}\Var{ip}, \Type{unw\_proc\_info\_t~*}\Var{pip}, \Type{void~*}\Var{arg});\\ 16 17 \section{Description} 18 19 The \Func{unw\_get\_proc\_info\_by\_ip}() routine returns the same 20 kind of auxiliary information about a procedure as 21 \Func{unw\_get\_proc\_info}(), except that the info is looked up by 22 instruction-pointer (IP) instead of a cursor. This is more flexible 23 because it is possible to look up the info for an arbitrary procedure, 24 even if it is not part of the current call-chain. However, since it 25 is more flexible, it also tends to run slower (and often much slower) 26 than \Func{unw\_get\_proc\_info}(). 27 28 The routine expects the followins arguments: \Var{as} is the 29 address-space in which the instruction-pointer should be looked up. 30 For a look-up in the local address-space, 31 \Var{unw\_local\_addr\_space} can be passed for this argument. 32 Argument \Var{ip} is the instruction-pointer for which the procedure 33 info should be looked up and \Var{pip} is a pointer to a structure of 34 type \Type{unw\_proc\_info\_t} which is used to return the info. 35 Lastly, \Var{arg} is the address-space argument that should be used 36 when accessing the address-space. It has the same purpose as the 37 argument of the same name for \Func{unw\_init\_remote}(). When 38 accessing the local address-space (first argument is 39 \Var{unw\_local\_addr\_space}), \Const{NULL} must be passed for this 40 argument. 41 42 Note that for the purposes of \Prog{libunwind}, the code of a 43 procedure is assumed to occupy a single, contiguous range of 44 addresses. For this reason, it is alwas possible to describe the 45 extent of a procedure with the \Var{start\_ip} and \Var{end\_ip} 46 members. If a single function/routine is split into multiple, 47 discontiguous pieces, \Prog{libunwind} will treat each piece as a 48 separate procedure. 49 50 \section{Return Value} 51 52 On successful completion, \Func{unw\_get\_proc\_info\_by\_ip}() 53 returns 0. Otherwise the negative value of one of the error-codes 54 below is returned. 55 56 \section{Thread and Signal Safety} 57 58 \Func{unw\_get\_proc\_info}() is thread-safe. If the local 59 address-space is passed in argument \Var{as}, this routine is also 60 safe to use from a signal handler. 61 62 \section{Errors} 63 64 \begin{Description} 65 \item[\Const{UNW\_EUNSPEC}] An unspecified error occurred. 66 \item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to locate 67 unwind-info for the procedure. 68 \item[\Const{UNW\_EBADVERSION}] The unwind-info for the procedure has 69 version or format that is not understood by \Prog{libunwind}. 70 \end{Description} 71 In addition, \Func{unw\_get\_proc\_info}() may return any error 72 returned by the \Func{access\_mem}() call-back (see 73 \Func{unw\_create\_addr\_space}(3)). 74 75 \section{See Also} 76 77 \SeeAlso{libunwind(3)}, 78 \SeeAlso{unw\_create\_addr\_space(3)}, 79 \SeeAlso{unw\_get\_proc\_name(3)}, 80 \SeeAlso{unw\_get\_proc\_info(3)}, 81 \SeeAlso{unw\_init\_remote(3)} 82 83 \section{Author} 84 85 \noindent 86 David Mosberger-Tang\\ 87 Email: \Email{dmosberger (a] gmail.com}\\ 88 WWW: \URL{http://www.nongnu.org/libunwind/}. 89 \LatexManEnd 90 91 \end{document} 92
