mirror of
https://github.com/tobast/libunwind-eh_elf.git
synced 2024-11-26 00:57:39 +01:00
Add documentation.
This commit is contained in:
Doug Moore
parent
fef5de6c45
commit
1568d7afa2
3 changed files with 150 additions and 0 deletions
|
|
@ -1,6 +1,7 @@
|
||||||
# man pages that go into section 3:
|
# man pages that go into section 3:
|
||||||
man3_MANS = libunwind.man libunwind-dynamic.man libunwind-ia64.man \
|
man3_MANS = libunwind.man libunwind-dynamic.man libunwind-ia64.man \
|
||||||
libunwind-ptrace.man libunwind-setjmp.man \
|
libunwind-ptrace.man libunwind-setjmp.man \
|
||||||
|
unw_apply_reg_state.man \
|
||||||
unw_backtrace.man \
|
unw_backtrace.man \
|
||||||
unw_flush_cache.man \
|
unw_flush_cache.man \
|
||||||
unw_get_accessors.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_create_addr_space.man \
|
||||||
unw_destroy_addr_space.man \
|
unw_destroy_addr_space.man \
|
||||||
unw_regname.man unw_resume.man \
|
unw_regname.man unw_resume.man \
|
||||||
|
unw_reg_states_iterate.man \
|
||||||
unw_set_caching_policy.man \
|
unw_set_caching_policy.man \
|
||||||
unw_set_cache_size.man \
|
unw_set_cache_size.man \
|
||||||
unw_set_fpreg.man \
|
unw_set_fpreg.man \
|
||||||
|
|
@ -29,6 +31,7 @@ man3_MANS = libunwind.man libunwind-dynamic.man libunwind-ia64.man \
|
||||||
EXTRA_DIST = NOTES libunwind.trans \
|
EXTRA_DIST = NOTES libunwind.trans \
|
||||||
libunwind.tex libunwind-dynamic.tex libunwind-ia64.tex \
|
libunwind.tex libunwind-dynamic.tex libunwind-ia64.tex \
|
||||||
libunwind-ptrace.tex libunwind-setjmp.tex \
|
libunwind-ptrace.tex libunwind-setjmp.tex \
|
||||||
|
unw_apply_reg_state.tex \
|
||||||
unw_backtrace.tex \
|
unw_backtrace.tex \
|
||||||
unw_flush_cache.tex \
|
unw_flush_cache.tex \
|
||||||
unw_get_accessors.tex \
|
unw_get_accessors.tex \
|
||||||
|
|
@ -43,6 +46,7 @@ EXTRA_DIST = NOTES libunwind.trans \
|
||||||
unw_is_signal_frame.tex \
|
unw_is_signal_frame.tex \
|
||||||
unw_create_addr_space.tex unw_destroy_addr_space.tex \
|
unw_create_addr_space.tex unw_destroy_addr_space.tex \
|
||||||
unw_regname.tex unw_resume.tex unw_set_caching_policy.tex \
|
unw_regname.tex unw_resume.tex unw_set_caching_policy.tex \
|
||||||
|
unw_reg_states_iterate.tex \
|
||||||
unw_set_cache_size.tex \
|
unw_set_cache_size.tex \
|
||||||
unw_set_fpreg.tex \
|
unw_set_fpreg.tex \
|
||||||
unw_set_reg.tex \
|
unw_set_reg.tex \
|
||||||
|
|
|
||||||
63
doc/unw_apply_reg_state.tex
Normal file
63
doc/unw_apply_reg_state.tex
Normal file
|
|
@ -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}
|
||||||
83
doc/unw_reg_states_iterate.tex
Normal file
83
doc/unw_reg_states_iterate.tex
Normal file
|
|
@ -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}
|
||||||
Loading…
Reference in a new issue