diff options
Diffstat (limited to 'src/third_party/unwind/dist/doc/unw_get_proc_info_by_ip.tex')
-rw-r--r-- | src/third_party/unwind/dist/doc/unw_get_proc_info_by_ip.tex | 91 |
1 files changed, 91 insertions, 0 deletions
diff --git a/src/third_party/unwind/dist/doc/unw_get_proc_info_by_ip.tex b/src/third_party/unwind/dist/doc/unw_get_proc_info_by_ip.tex new file mode 100644 index 00000000000..5e1d5d247eb --- /dev/null +++ b/src/third_party/unwind/dist/doc/unw_get_proc_info_by_ip.tex @@ -0,0 +1,91 @@ +\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} |