Home | History | Annotate | Download | only in doc 
      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 
     19 The \Func{unw\_getcontext}() routine initializes the context structure
     20 pointed to by \Var{ucp} with the machine-state of the call-site.  The
     21 exact set of registers stored by \Func{unw\_getcontext}() is
     22 platform-specific, but, in general, at least all preserved
     23 (``callee-saved'') and all frame-related registers, such as the
     24 stack-pointer, will be stored.
     25 
     26 This routine is normally implemented as a macro and applications
     27 should not attempt to take its address.
     28 
     29 \section{Platform-specific Notes}
     30 
     31 On IA-64, \Type{unw\_context\_t} has a layout that is compatible with
     32 that of \Type{ucontext\_t} and such structures can be initialized with
     33 \Func{getcontext}() instead of \Func{unw\_getcontext}().  However, the
     34 reverse is \emph{not} true and it is \emph{not} safe to use structures
     35 initialized by \Func{unw\_getcontext()} in places where a structure
     36 initialized by \Func{getcontext()} is expected. The reason for this
     37 asymmetry is that \Func{unw\_getcontext()} is optimized for maximum
     38 performance and does not, for example, save the signal mask.
     39 
     40 \section{Return Value}
     41 
     42 On successful completion, \Func{unw\_getcontext}() returns 0.
     43 Otherwise, 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
     48 from 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
     58 David Mosberger-Tang\\
     59 Email: \Email{dmosberger (a] gmail.com}\\
     60 WWW: \URL{http://www.nongnu.org/libunwind/}.
     61 \LatexManEnd
     62 
     63 \end{document}
     64