Add documentation.

3 files changed, 150 insertions, 0 deletions

diff --git a/doc/Makefile.am b/doc/Makefile.am
index a3eb8238..9b75e6d8 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,6 +1,7 @@
 # man pages that go into section 3:
 man3_MANS = libunwind.man libunwind-dynamic.man libunwind-ia64.man	\
 	libunwind-ptrace.man libunwind-setjmp.man			\
+	unw_apply_reg_state.man						\
 	unw_backtrace.man						\
 	unw_flush_cache.man						\
 	unw_get_accessors.man						\
@@ -17,6 +18,7 @@ man3_MANS = libunwind.man libunwind-dynamic.man libunwind-ia64.man	\
 	unw_create_addr_space.man					\
 	unw_destroy_addr_space.man					\
 	unw_regname.man unw_resume.man					\
+	unw_reg_states_iterate.man					\
 	unw_set_caching_policy.man					\
 	unw_set_cache_size.man						\
 	unw_set_fpreg.man						\
@@ -29,6 +31,7 @@ man3_MANS = libunwind.man libunwind-dynamic.man libunwind-ia64.man	\
 EXTRA_DIST = NOTES libunwind.trans					\
 	libunwind.tex libunwind-dynamic.tex libunwind-ia64.tex		\
 	libunwind-ptrace.tex libunwind-setjmp.tex			\
+	unw_apply_reg_state.tex						\
 	unw_backtrace.tex						\
 	unw_flush_cache.tex						\
 	unw_get_accessors.tex						\
@@ -43,6 +46,7 @@ EXTRA_DIST = NOTES libunwind.trans					\
 	unw_is_signal_frame.tex						\
 	unw_create_addr_space.tex unw_destroy_addr_space.tex		\
 	unw_regname.tex unw_resume.tex unw_set_caching_policy.tex	\
+	unw_reg_states_iterate.tex					\
 	unw_set_cache_size.tex						\
 	unw_set_fpreg.tex						\
 	unw_set_reg.tex							\
diff --git a/doc/unw_apply_reg_state.tex b/doc/unw_apply_reg_state.tex
new file mode 100644
index 00000000..c67cc3eb
--- /dev/null
+++ b/doc/unw_apply_reg_state.tex
@@ -0,0 +1,63 @@
+\documentclass{article}
+\usepackage[fancyhdr,pdf]{latex2man}
+
+\input{common.tex}
+
+\begin{document}
+
+\begin{Name}{3}{unw\_apply\_reg\_state}{David Mosberger-Tang}{Programming Library}{unw\_apply\_reg\_state}unw\_apply\_reg\_state -- apply a register state update to a cursor
+\end{Name}
+
+\section{Synopsis}
+
+\File{\#include $<$libunwind.h$>$}\\
+
+\Type{int}
+\Func{unw\_apply\_reg\_state}(\Type{unw\_cursor\_t~*}\Var{cp},
+\Type{void~*}\Var{reg\_states\_data});\\
+
+\section{Description}
+
+The \Func{unw\_apply\_reg\_state}() routine updates the register values
+of a cursor according to the instructions in \Var{reg\_states\_data},
+which have been obtained by calling \Var{unw\_reg\_states\_iterate}.
+
+\section{Return Value}
+
+On successful completion, \Func{unw\_apply\_reg\_state}() returns 0.
+Otherwise the negative value of one of the error-codes below is
+returned.
+
+\section{Thread and Signal Safety}
+
+\Func{unw\_apply\_reg\_state}() 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\_apply\_reg\_state}() 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\_reg\_states\_iterate(3)}
+
+\section{Author}
+
+\noindent
+David Mosberger-Tang\\
+Email: \Email{dmosberger@gmail.com}\\
+WWW: \URL{http://www.nongnu.org/libunwind/}.
+\LatexManEnd
+
+\end{document}
diff --git a/doc/unw_reg_states_iterate.tex b/doc/unw_reg_states_iterate.tex
new file mode 100644
index 00000000..36c9b548
--- /dev/null
+++ b/doc/unw_reg_states_iterate.tex
@@ -0,0 +1,83 @@
+\documentclass{article}
+\usepackage[fancyhdr,pdf]{latex2man}
+
+\input{common.tex}
+
+\begin{document}
+
+\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
+\end{Name}
+
+\section{Synopsis}
+
+\File{\#include $<$libunwind.h$>$}\\
+
+\Type{int} \Func{unw\_reg\_states\_iterate}(\Type{unw\_cursor\_t~*}\Var{cp}, \Type{unw\_reg\_states\_callback}\Var{cb}, \Type{void~*}\Var{token});\\
+
+\section{Description}
+
+The \Func{unw\_reg\_states\_iterate}() routine provides
+information about the procedure that created the stack frame
+identified by argument \Var{cp}.  The \Var{cb} argument is a pointer
+to a function of type \Type{unw\_reg\_states\_callback} which is used to
+return the information.  The function \Type{unw\_reg\_states\_callback} has the
+following definition:
+
+\Type{int} (~*\Var{unw\_reg\_states\_callback})(\Type{void~*}\Var{token},
+			\Type{void~*}\Var{reg\_states\_data},
+			\Type{size\_t} \Var{reg\_states\_data\_size},
+			\Type{unw\_word\_t} \Var{start\_ip}, \Type{unw\_word\_t} \Var{end\_ip});
+
+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:
+\begin{description}
+\item[\Type{void~*} \Var{token}] The token value passed to \Var{unw\_reg\_states\_callback}. \\
+\item[\Type{void~*} \Var{reg\_states\_data}] A pointer to data about
+  updating register values. This data, or a copy of it, can be passed
+  to \Var{unw\_apply\_reg\_state}.\\
+\item[\Type{int} \Var{reg\_states\_data\_size}] The size of the register update data. \\
+\item[\Type{unw\_word\_t} \Var{start\_ip}] The address of the first
+  instruction of the address range.  \\
+\item[\Type{unw\_word\_t} \Var{end\_ip}] The address of the first
+  instruction \emph{beyond} the end of the address range.  \\
+\end{description}
+
+\section{Return Value}
+
+On successful completion, \Func{unw\_reg\_states\_iterate}() returns
+0.  If the callback function returns a nonzero value, that indicates
+failure and the function returns immediately.  Otherwise the negative
+value of one of the error-codes below is returned.
+
+\section{Thread and Signal Safety}
+
+\Func{unw\_reg\_states\_iterate}() 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\_reg\_states\_iterate}() 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\_apply\_reg\_state(3)}
+
+\section{Author}
+
+\noindent
+David Mosberger-Tang\\
+Email: \Email{dmosberger@gmail.com}\\
+WWW: \URL{http://www.nongnu.org/libunwind/}.
+\LatexManEnd
+
+\end{document}