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 19The \Func{unw\_get\_proc\_info\_by\_ip}() routine returns the same 20kind of auxiliary information about a procedure as 21\Func{unw\_get\_proc\_info}(), except that the info is looked up by 22instruction-pointer (IP) instead of a cursor. This is more flexible 23because it is possible to look up the info for an arbitrary procedure, 24even if it is not part of the current call-chain. However, since it 25is more flexible, it also tends to run slower (and often much slower) 26than \Func{unw\_get\_proc\_info}(). 27 28The routine expects the followins arguments: \Var{as} is the 29address-space in which the instruction-pointer should be looked up. 30For a look-up in the local address-space, 31\Var{unw\_local\_addr\_space} can be passed for this argument. 32Argument \Var{ip} is the instruction-pointer for which the procedure 33info should be looked up and \Var{pip} is a pointer to a structure of 34type \Type{unw\_proc\_info\_t} which is used to return the info. 35Lastly, \Var{arg} is the address-space argument that should be used 36when accessing the address-space. It has the same purpose as the 37argument of the same name for \Func{unw\_init\_remote}(). When 38accessing the local address-space (first argument is 39\Var{unw\_local\_addr\_space}), \Const{NULL} must be passed for this 40argument. 41 42Note that for the purposes of \Prog{libunwind}, the code of a 43procedure is assumed to occupy a single, contiguous range of 44addresses. For this reason, it is alwas possible to describe the 45extent of a procedure with the \Var{start\_ip} and \Var{end\_ip} 46members. If a single function/routine is split into multiple, 47discontiguous pieces, \Prog{libunwind} will treat each piece as a 48separate procedure. 49 50\section{Return Value} 51 52On successful completion, \Func{unw\_get\_proc\_info\_by\_ip}() 53returns 0. Otherwise the negative value of one of the error-codes 54below is returned. 55 56\section{Thread and Signal Safety} 57 58\Func{unw\_get\_proc\_info}() is thread-safe. If the local 59address-space is passed in argument \Var{as}, this routine is also 60safe 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} 71In addition, \Func{unw\_get\_proc\_info}() may return any error 72returned 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 86David Mosberger-Tang\\ 87Email: \Email{dmosberger@gmail.com}\\ 88WWW: \URL{http://www.nongnu.org/libunwind/}. 89\LatexManEnd 90 91\end{document} 92