xref: /external/libunwind/doc/unw_getcontext.tex

\documentclass{article}
\usepackage[fancyhdr,pdf]{latex2man}

\input{common.tex}

\begin{document}

\begin{Name}{3}{unw\_getcontext}{David Mosberger-Tang}{Programming Library}{unw\_getcontext}unw\_getcontext -- get initial machine-state
\end{Name}

\section{Synopsis}

\File{\#include $<$libunwind.h$>$}\\

\Type{int} \Func{unw\_getcontext}(\Type{unw\_context\_t~*}\Var{ucp});\\

\section{Description}

The \Func{unw\_getcontext}() routine initializes the context structure
pointed to by \Var{ucp} with the machine-state of the call-site.  The
exact set of registers stored by \Func{unw\_getcontext}() is
platform-specific, but, in general, at least all preserved
(``callee-saved'') and all frame-related registers, such as the
stack-pointer, will be stored.

This routine is normally implemented as a macro and applications
should not attempt to take its address.

\section{Platform-specific Notes}

On IA-64, \Type{unw\_context\_t} has a layout that is compatible with
that of \Type{ucontext\_t} and such structures can be initialized with
\Func{getcontext}() instead of \Func{unw\_getcontext}().  However, the
reverse is \emph{not} true and it is \emph{not} safe to use structures
initialized by \Func{unw\_getcontext()} in places where a structure
initialized by \Func{getcontext()} is expected. The reason for this
asymmetry is that \Func{unw\_getcontext()} is optimized for maximum
performance and does not, for example, save the signal mask.

\section{Return Value}

On successful completion, \Func{unw\_getcontext}() returns 0.
Otherwise, a value of -1 is returned.

\section{Thread and Signal Safety}

\Func{unw\_getcontext}() is thread-safe as well as safe to use
from a signal handler.

\section{See Also}

\SeeAlso{libunwind(3)},
\SeeAlso{unw\_init\_local(3)}

\section{Author}

\noindent
David Mosberger-Tang\\
Email: \Email{dmosberger@gmail.com}\\
WWW: \URL{http://www.nongnu.org/libunwind/}.
\LatexManEnd

\end{document}