doc/unw_reg_states_iterate.tex

   1 \documentclass{article}
   2 \usepackage[fancyhdr,pdf]{latex2man}
   3
   4 \input{common.tex}
   5
   6 \begin{document}
   7
   8 \begin{Name}{3}{unw\_reg\_states\_iterate}{David Mosberger-Tang}{Programming Library}{unw\_reg\_states\_iterate}unw\_reg\_states\_iterate -- get register state info on current procedure
   9 \end{Name}
  10
  11 \section{Synopsis}
  12
  13 \File{\#include $<$libunwind.h$>$}\\
  14
  15 \Type{int} \Func{unw\_reg\_states\_iterate}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{unw\_reg\_states\_callback}\Var{cb}, \Type{void~*}\Var{token});\\
  16
  17 \section{Description}
  18
  19 The \Func{unw\_reg\_states\_iterate}() routine provides
  20 information about the procedure that created the stack frame
  21 identified by argument \Var{cp}.  The \Var{cb} argument is a pointer
  22 to a function of type \Type{unw\_reg\_states\_callback} which is used to
  23 return the information.  The function \Type{unw\_reg\_states\_callback} has the
  24 following definition:
  25
  26 \Type{int} (~*\Var{unw\_reg\_states\_callback})(\Type{void~*}\Var{token},
  27                         \Type{void~*}\Var{reg\_states\_data},
  28                         \Type{size\_t} \Var{reg\_states\_data\_size},
  29                         \Type{unw\_word\_t} \Var{start\_ip}, \Type{unw\_word\_t} \Var{end\_ip});
  30
  31 The callback function may be invoked several times for each call of \Func{unw\_reg\_states\_iterate}. Each call is associcated with a instruction address range and a set of instructions on how to update register values when returning from the procedure in that address range.  For each invocation, the arguments to the callback function are:
  32 \begin{description}
  33 \item[\Type{void~*} \Var{token}] The token value passed to \Var{unw\_reg\_states\_callback}. \\
  34 \item[\Type{void~*} \Var{reg\_states\_data}] A pointer to data about
  35   updating register values. This data, or a copy of it, can be passed
  36   to \Var{unw\_apply\_reg\_state}.\\
  37 \item[\Type{int} \Var{reg\_states\_data\_size}] The size of the register update data. \\
  38 \item[\Type{unw\_word\_t} \Var{start\_ip}] The address of the first
  39   instruction of the address range.  \\
  40 \item[\Type{unw\_word\_t} \Var{end\_ip}] The address of the first
  41   instruction \emph{beyond} the end of the address range.  \\
  42 \end{description}
  43
  44 \section{Return Value}
  45
  46 On successful completion, \Func{unw\_reg\_states\_iterate}() returns
  47 0.  If the callback function returns a nonzero value, that indicates
  48 failure and the function returns immediately.  Otherwise the negative
  49 value of one of the error-codes below is returned.
  50
  51 \section{Thread and Signal Safety}
  52
  53 \Func{unw\_reg\_states\_iterate}() is thread-safe.  If cursor \Var{cp} is
  54 in the local address-space, this routine is also safe to use from a
  55 signal handler.
  56
  57 \section{Errors}
  58
  59 \begin{Description}
  60 \item[\Const{UNW\_EUNSPEC}] An unspecified error occurred.
  61 \item[\Const{UNW\_ENOINFO}] \Prog{Libunwind} was unable to locate
  62   unwind-info for the procedure.
  63 \item[\Const{UNW\_EBADVERSION}] The unwind-info for the procedure has
  64   version or format that is not understood by \Prog{libunwind}.
  65 \end{Description}
  66 In addition, \Func{unw\_reg\_states\_iterate}() may return any error
  67 returned by the \Func{access\_mem}() call-back (see
  68 \Func{unw\_create\_addr\_space}(3)).
  69
  70 \section{See Also}
  71
  72 \SeeAlso{libunwind(3)},
  73 \SeeAlso{unw\_apply\_reg\_state(3)}
  74
  75 \section{Author}
  76
  77 \noindent
  78 David Mosberger-Tang\\
  79 Email: \Email{dmosberger@gmail.com}\\
  80 WWW: \URL{http://www.nongnu.org/libunwind/}.
  81 \LatexManEnd
  82
  83 \end{document}