doc/unw_getcontext.man

   1 '\" t
   2 .\" Manual page created with latex2man on Thu Aug 16 09:44:45 MDT 2007
   3 .\" NOTE: This file is generated, DO NOT EDIT.
   4 .de Vb
   5 .ft CW
   6 .nf
   7 ..
   8 .de Ve
   9 .ft R
  10
  11 .fi
  12 ..
  13 .TH "UNW\\_GETCONTEXT" "3" "16 August 2007" "Programming Library " "Programming Library "
  14 .SH NAME
  15 unw_getcontext
  16 \-\- get initial machine\-state
  17 .PP
  18 .SH SYNOPSIS
  19
  20 .PP
  21 #include <libunwind.h>
  22 .br
  23 .PP
  24 int
  25 unw_getcontext(unw_context_t *ucp);
  26 .br
  27 .PP
  28 .SH DESCRIPTION
  29
  30 .PP
  31 The unw_getcontext()
  32 routine initializes the context structure
  33 pointed to by ucp
  34 with the machine\-state of the call\-site. The
  35 exact set of registers stored by unw_getcontext()
  36 is
  37 platform\-specific, but, in general, at least all preserved
  38 (``callee\-saved\&'') and all frame\-related registers, such as the
  39 stack\-pointer, will be stored.
  40 .PP
  41 This routine is normally implemented as a macro and applications
  42 should not attempt to take its address.
  43 .PP
  44 .SH PLATFORM\-SPECIFIC NOTES
  45
  46 .PP
  47 On IA\-64, unw_context_t
  48 has a layout that is compatible with
  49 that of ucontext_t
  50 and such structures can be initialized with
  51 getcontext()
  52 instead of unw_getcontext().
  53 However, the
  54 reverse is \fInot\fP
  55 true and it is \fInot\fP
  56 safe to use structures
  57 initialized by unw_getcontext()
  58 in places where a structure
  59 initialized by getcontext()
  60 is expected. The reason for this
  61 asymmetry is that unw_getcontext()
  62 is optimized for maximum
  63 performance and does not, for example, save the signal mask.
  64 .PP
  65 .SH RETURN VALUE
  66
  67 .PP
  68 On successful completion, unw_getcontext()
  69 returns 0.
  70 Otherwise, a value of \-1 is returned.
  71 .PP
  72 .SH THREAD AND SIGNAL SAFETY
  73
  74 .PP
  75 unw_getcontext()
  76 is thread\-safe as well as safe to use
  77 from a signal handler.
  78 .PP
  79 .SH SEE ALSO
  80
  81 .PP
  82 libunwind(3),
  83 unw_init_local(3)
  84 .PP
  85 .SH AUTHOR
  86
  87 .PP
  88 David Mosberger\-Tang
  89 .br
  90 Email: \fBdmosberger@gmail.com\fP
  91 .br
  92 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
  93 .\" NOTE: This file is generated, DO NOT EDIT.