2003-12-04 08:34:21 +01:00
\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 as well as 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\\
Hewlett-Packard Labs\\
Palo-Alto, CA 94304\\
Email: \Email { davidm@hpl.hp.com} \\
WWW: \URL { http://www.hpl.hp.com/research/linux/libunwind/} .
\LatexManEnd
\end { document}
