| \documentclass{article} |
| \usepackage[fancyhdr,pdf]{latex2man} |
| |
| \input{common.tex} |
| |
| \begin{document} |
| |
| \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 |
| \end{Name} |
| |
| \section{Synopsis} |
| |
| \File{\#include $<$libunwind.h$>$}\\ |
| |
| \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});\\ |
| |
| \section{Description} |
| |
| The \Func{unw\_get\_proc\_info\_by\_ip}() routine returns the same |
| kind of auxiliary information about a procedure as |
| \Func{unw\_get\_proc\_info}(), except that the info is looked up by |
| instruction-pointer (IP) instead of a cursor. This is more flexible |
| because it is possible to look up the info for an arbitrary procedure, |
| even if it is not part of the current call-chain. However, since it |
| is more flexible, it also tends to run slower (and often much slower) |
| than \Func{unw\_get\_proc\_info}(). |
| |
| The routine expects the followins arguments: \Var{as} is the |
| address-space in which the instruction-pointer should be looked up. |
| For a look-up in the local address-space, |
| \Var{unw\_local\_addr\_space} can be passed for this argument. |
| Argument \Var{ip} is the instruction-pointer for which the procedure |
| info should be looked up and \Var{pip} is a pointer to a structure of |
| type \Type{unw\_proc\_info\_t} which is used to return the info. |
| Lastly, \Var{arg} is the address-space argument that should be used |
| when accessing the address-space. It has the same purpose as the |
| argument of the same name for \Func{unw\_init\_remote}(). When |
| accessing the local address-space (first argument is |
| \Var{unw\_local\_addr\_space}), \Const{NULL} must be passed for this |
| argument. |
| |
| Note that for the purposes of \Prog{libunwind}, the code of a |
| procedure is assumed to occupy a single, contiguous range of |
| addresses. For this reason, it is alwas possible to describe the |
| extent of a procedure with the \Var{start\_ip} and \Var{end\_ip} |
| members. If a single function/routine is split into multiple, |
| discontiguous pieces, \Prog{libunwind} will treat each piece as a |
| separate procedure. |
| |
| \section{Return Value} |
| |
| On successful completion, \Func{unw\_get\_proc\_info\_by\_ip}() |
| returns 0. Otherwise the negative value of one of the error-codes |
| below is returned. |
| |
| \section{Thread and Signal Safety} |
| |
| \Func{unw\_get\_proc\_info}() is thread-safe. If the local |
| address-space is passed in argument \Var{as}, this routine is also |
| safe to use from a signal handler. |
| |
| \section{Errors} |
| |
| \begin{Description} |
| \item[\Const{UNW\_EUNSPEC}] An unspecified error occurred. |
| \item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to locate |
| unwind-info for the procedure. |
| \item[\Const{UNW\_EBADVERSION}] The unwind-info for the procedure has |
| version or format that is not understood by \Prog{libunwind}. |
| \end{Description} |
| In addition, \Func{unw\_get\_proc\_info}() may return any error |
| returned by the \Func{access\_mem}() call-back (see |
| \Func{unw\_create\_addr\_space}(3)). |
| |
| \section{See Also} |
| |
| \SeeAlso{libunwind(3)}, |
| \SeeAlso{unw\_create\_addr\_space(3)}, |
| \SeeAlso{unw\_get\_proc\_name(3)}, |
| \SeeAlso{unw\_get\_proc\_info(3)}, |
| \SeeAlso{unw\_init\_remote(3)} |
| |
| \section{Author} |
| |
| \noindent |
| David Mosberger-Tang\\ |
| Email: \Email{dmosberger@gmail.com}\\ |
| WWW: \URL{http://www.nongnu.org/libunwind/}. |
| \LatexManEnd |
| |
| \end{document} |