doc/unw_step.tex

   1 \documentclass{article}
   2 \usepackage[fancyhdr,pdf]{latex2man}
   3
   4 \input{common.tex}
   5
   6 \begin{document}
   7
   8 \begin{Name}{3}{unw\_step}{David Mosberger-Tang}{Programming Library}{unw\_step}unw\_step -- advance to next stack frame
   9 \end{Name}
  10
  11 \section{Synopsis}
  12
  13 \File{\#include $<$libunwind.h$>$}\\
  14
  15 \Type{int} \Func{unw\_step}(\Type{unw\_cursor\_t~*}\Var{cp});\\
  16
  17 \section{Description}
  18
  19 The \Func{unw\_step}() routine advances the unwind cursor \Var{cp} to
  20 the next older, less deeply nested stack frame.
  21
  22 \section{Return Value}
  23
  24 On successful completion, \Func{unw\_step}() returns a positive value
  25 if the updated cursor refers to a valid stack frame, or 0 if the
  26 previous stack frame was the last frame in the chain.  On error, the
  27 negative value of one of the error-codes below is returned.
  28
  29 \section{Thread and Signal Safety}
  30
  31 \Func{unw\_step}() is thread-safe.  If cursor \Var{cp} is in the local
  32 address-space, this routine is also safe to use from a signal handler.
  33
  34 \section{Errors}
  35
  36 \begin{Description}
  37 \item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
  38 \item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to locate the
  39   unwind-info needed to complete the operation.
  40 \item[\Const{UNW\_EBADVERSION}] The unwind-info needed to complete the
  41   operation has a version or a format that is not understood by
  42   \Prog{libunwind}.
  43 \item[\Const{UNW\_EINVALIDIP}] The instruction-pointer
  44   (``program-counter'') of the next stack frame is invalid (e.g., not
  45   properly aligned).
  46 \item[\Const{UNW\_EBADFRAME}] The next stack frame is invalid.
  47 \item[\Const{UNW\_ESTOPUNWIND}] Returned if a call to
  48   \Func{find\_proc\_info}() returned -\Const{UNW\_ESTOPUNWIND}.
  49 \end{Description}
  50 In addition, \Func{unw\_step}() may return any error returned by the
  51 \Func{find\_proc\_info}(), \Func{get\_dyn\_info\_list\_addr}(),
  52 \Func{access\_mem}(), \Func{access\_reg}(), or \Func{access\_fpreg}()
  53 call-backs (see \Func{unw\_create\_addr\_space}(3)).
  54
  55 \section{See Also}
  56
  57 \SeeAlso{libunwind(3)},
  58 \SeeAlso{unw\_create\_addr\_space(3)}
  59
  60 \section{Author}
  61
  62 \noindent
  63 David Mosberger-Tang\\
  64 Email: \Email{dmosberger@gmail.com}\\
  65 WWW: \URL{http://www.nongnu.org/libunwind/}.
  66 \LatexManEnd
  67
  68 \end{document}