% This Source Code Form is subject to the terms of the Mozilla Public
% License, v. 2.0. If a copy of the MPL was not distributed with this
% file, You can obtain one at http://mozilla.org/MPL/2.0/.

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

\input{common.tex}

\begin{document}

\begin{Name}{3}{unw\_step}{David Mosberger-Tang}{Programming Library}{unw\_step}unw\_step -- advance to next stack frame
\end{Name}

\section{Synopsis}

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

\Type{int} \Func{unw\_step}(\Type{unw\_cursor\_t~*}\Var{cp});\\

\section{Description}

The \Func{unw\_step}() routine advances the unwind cursor \Var{cp} to
the next older, less deeply nested stack frame.

\section{Return Value}

On successful completion, \Func{unw\_step}() returns a positive value
if the updated cursor refers to a valid stack frame, or 0 if the
previous stack frame was the last frame in the chain.  On error, the
negative value of one of the error-codes below is returned.

\section{Thread and Signal Safety}

\Func{unw\_step}() 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 the
  unwind-info needed to complete the operation.
\item[\Const{UNW\_EBADVERSION}] The unwind-info needed to complete the
  operation has a version or a format that is not understood by
  \Prog{libunwind}.
\item[\Const{UNW\_EINVALIDIP}] The instruction-pointer
  (``program-counter'') of the next stack frame is invalid (e.g., not
  properly aligned).
\item[\Const{UNW\_EBADFRAME}] The next stack frame is invalid.
\item[\Const{UNW\_ESTOPUNWIND}] Returned if a call to
  \Func{find\_proc\_info}() returned -\Const{UNW\_ESTOPUNWIND}.
\end{Description}
In addition, \Func{unw\_step}() may return any error returned by the
\Func{find\_proc\_info}(), \Func{get\_dyn\_info\_list\_addr}(),
\Func{access\_mem}(), \Func{access\_reg}(), or \Func{access\_fpreg}()
call-backs (see \Func{unw\_create\_addr\_space}(3)).

\section{See Also}

\SeeAlso{libunwind(3)},
\SeeAlso{unw\_create\_addr\_space(3)}

\section{Author}

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

\end{document}
