\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}

\input{common.tex}

\begin{document}

\begin{Name}{3libunwind}{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 following 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 always 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\_by\_ip}() 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\_by\_ip}() may return any
error returned by the \Func{access\_mem}() callback (see
\Func{unw\_create\_addr\_space}(3libunwind)).

\section{See Also}

\SeeAlso{libunwind}(3libunwind),
\SeeAlso{unw\_create\_addr\_space}(3libunwind),
\SeeAlso{unw\_get\_proc\_name}(3libunwind),
\SeeAlso{unw\_get\_proc\_info}(3libunwind),
\SeeAlso{unw\_init\_remote}(3libunwind)

\section{Author}

\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd

\end{document}
