libunwind-eh_elf/doc/unw_get_proc_info.tex

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

\input{common.tex}

\begin{document}

\begin{Name}{3}{unw\_get\_proc\_info}{David Mosberger-Tang}{Programming Library}{unw\_get\_proc\_info}unw\_get\_proc\_info -- get info on current procedure
\end{Name}

\section{Synopsis}

\File{\#include $<$libunwind.h$>$}\\

\Type{int} \Func{unw\_get\_proc\_info}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{unw\_proc\_info\_t~*}\Var{pip});\\

\section{Description}

The \Func{unw\_get\_proc\_info}() routine returns auxiliary
information about the procedure that created the stack frame
identified by argument \Var{cp}.  The \Var{pip} argument is a pointer
to a structure of type \Type{unw\_proc\_info\_t} which is used to
return the information.  The \Type{unw\_proc\_info\_t} has the
following members:
\begin{description}
\item[\Type{unw\_word\_t} \Var{start\_ip}] The address of the first
  instruction of the procedure.  If this address cannot be determined
  (e.g., due to lack of unwind information), the \Var{start\_ip}
  member is cleared to 0.  \\
\item[\Type{unw\_word\_t} \Var{end\_ip}] The address of the first
  instruction \emph{beyond} the end of the procedure.  If this address
  cannot be determined (e.g., due to lack of unwind information),
  the \Var{end\_ip} member is cleared to 0.  \\
\item[\Type{unw\_word\_t} \Var{lsda}] The address of the
  language-specific data-area (LSDA).  This area normally contains
  language-specific information needed during exception handling.  If
  the procedure has no such area, this member is cleared to 0.  \\
\item[\Type{unw\_word\_t} \Var{handler}] The address of the exception
  handler routine.  This is sometimes called the \emph{personality}
  routine.  If the procedure does not define
  a personality routine, the \Var{handler} member is cleared to 0.  \\
\item[\Type{unw\_word\_t} \Var{gp}] The global-pointer of the
  procedure.  On platforms that do not use a global pointer, this
  member may contain an undefined value.  On all other platforms, it
  must be set either to the correct global-pointer value of the
  procedure or to 0 if the proper global-pointer cannot be
  obtained for some reason.  \\
\item[\Type{unw\_word\_t} \Var{flags}] A set of flags.  There are
  currently no target-independent flags.  For the IA-64 target, the
  flag \Const{UNW_PI_FLAG_IA64_RBS_SWITCH} is set if the
  procedure may switch the register-backing store.\\
\item[\Type{int} \Var{format}] The format of the unwind-info for this
  procedure.  If the unwind-info consists of dynamic procedure info,
  \Var{format} is equal to \Const{UNW\_INFO\_FORMAT\_DYNAMIC}.  If the
  unwind-info consists of a (target-specific) unwind table, it is
  equal to to \Const{UNW\_INFO\_FORMAT\_TABLE}.  All other values are
  reserved for future use by \Prog{libunwind}.  This member exists
  for use by the \Func{find\_proc\_info}() call-back (see
  \Func{unw\_create\_addr\_space}(3)).  The
  \Func{unw\_get\_proc\_info}() routine
  may return an undefined value in this member. \\
\item[\Type{int} \Var{unwind\_info\_size}] The size of the unwind-info
  in bytes.  This member exists for use by the
  \Func{find\_proc\_info}() call-back (see
  \Func{unw\_create\_addr\_space}(3)).  The
  \Func{unw\_get\_proc\_info}() routine
  may return an undefined value in this member.\\
\item[\Type{void~*}\Var{unwind\_info}] The pointer to the unwind-info.
  If no unwind info is available, this member must be set to
  \Const{NULL}.  This member exists for use by the
  \Func{find\_proc\_info}() call-back (see
  \Func{unw\_create\_addr\_space}(3)).  The
  \Func{unw\_get\_proc\_info}() routine
  may return an undefined value in this member.\\
\end{description}
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}() 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 cursor \Var{cp} is
in the local address-space, 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)}

\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}