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 19The \Func{unw\_reg\_states\_iterate}() routine provides 20information about the procedure that created the stack frame 21identified by argument \Var{cp}. The \Var{cb} argument is a pointer 22to a function of type \Type{unw\_reg\_states\_callback} which is used to 23return the information. The function \Type{unw\_reg\_states\_callback} has the 24following 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 31The 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 46On successful completion, \Func{unw\_reg\_states\_iterate}() returns 470. If the callback function returns a nonzero value, that indicates 48failure and the function returns immediately. Otherwise the negative 49value 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 54in the local address-space, this routine is also safe to use from a 55signal 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} 66In addition, \Func{unw\_reg\_states\_iterate}() may return any error 67returned 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 78David Mosberger-Tang\\ 79Email: \Email{dmosberger@gmail.com}\\ 80WWW: \URL{http://www.nongnu.org/libunwind/}. 81\LatexManEnd 82 83\end{document} 84