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