1\documentclass{article}
2\usepackage[fancyhdr,pdf]{latex2man}
3
4\input{common.tex}
5
6\begin{document}
7
8\begin{Name}{3}{unw\_getcontext}{David Mosberger-Tang}{Programming Library}{unw\_getcontext}unw\_getcontext -- get initial machine-state
9\end{Name}
10
11\section{Synopsis}
12
13\File{\#include $<$libunwind.h$>$}\\
14
15\Type{int} \Func{unw\_getcontext}(\Type{unw\_context\_t~*}\Var{ucp});\\
16
17\section{Description}
18
19The \Func{unw\_getcontext}() routine initializes the context structure
20pointed to by \Var{ucp} with the machine-state of the call-site.  The
21exact set of registers stored by \Func{unw\_getcontext}() is
22platform-specific, but, in general, at least all preserved
23(``callee-saved'') and all frame-related registers, such as the
24stack-pointer, will be stored.
25
26This routine is normally implemented as a macro and applications
27should not attempt to take its address.
28
29\section{Platform-specific Notes}
30
31On IA-64, \Type{unw\_context\_t} has a layout that is compatible with
32that of \Type{ucontext\_t} and such structures can be initialized with
33\Func{getcontext}() instead of \Func{unw\_getcontext}().  However, the
34reverse is \emph{not} true and it is \emph{not} safe to use structures
35initialized by \Func{unw\_getcontext()} in places where a structure
36initialized by \Func{getcontext()} is expected. The reason for this
37asymmetry is that \Func{unw\_getcontext()} is optimized for maximum
38performance and does not, for example, save the signal mask.
39
40\section{Return Value}
41
42On successful completion, \Func{unw\_getcontext}() returns 0.
43Otherwise, a value of -1 is returned.
44
45\section{Thread and Signal Safety}
46
47\Func{unw\_getcontext}() is thread-safe as well as safe to use
48from a signal handler.
49
50\section{See Also}
51
52\SeeAlso{libunwind(3)},
53\SeeAlso{unw\_init\_local(3)}
54
55\section{Author}
56
57\noindent
58David Mosberger-Tang\\
59Email: \Email{dmosberger@gmail.com}\\
60WWW: \URL{http://www.nongnu.org/libunwind/}.
61\LatexManEnd
62
63\end{document}
64