doc/libunwind-setjmp.man

   1 '\" t
   2 .\" Manual page created with latex2man on Thu Aug 16 09:44:44 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 "LIBUNWIND\-SETJMP" "3" "16 August 2007" "Programming Library " "Programming Library "
  14 .SH NAME
  15 libunwind\-setjmp
  16 \-\- libunwind\-based non\-local gotos
  17 .PP
  18 .SH SYNOPSIS
  19
  20 .PP
  21 #include <setjmp.h>
  22 .br
  23 .PP
  24 int
  25 setjmp(jmp_buf env);
  26 .br
  27 void
  28 longjmp(jmp_buf env,
  29 int val);
  30 .br
  31 int
  32 _setjmp(jmp_buf env);
  33 .br
  34 void
  35 _longjmp(jmp_buf env,
  36 int val);
  37 .br
  38 int
  39 sigsetjmp(sigjmp_buf env,
  40 int savemask);
  41 .br
  42 void
  43 siglongjmp(sigjmp_buf env,
  44 int val);
  45 .br
  46 .PP
  47 .SH DESCRIPTION
  48
  49 .PP
  50 The unwind\-setjmp
  51 library offers a libunwind\-based
  52 implementation of non\-local gotos. This implementation is intended to
  53 be a drop\-in replacement for the normal, system\-provided routines of
  54 the same name. The main advantage of using the unwind\-setjmp
  55 library is that setting up a non\-local goto via one of the
  56 setjmp()
  57 routines is very fast. Typically, just 2 or 3 words
  58 need to be saved in the jump\-buffer (plus one call to
  59 sigprocmask(2),
  60 in the case of sigsetjmp).
  61 On the
  62 other hand, executing a non\-local goto by calling one of the
  63 longjmp()
  64 routines tends to be much slower than with the
  65 system\-provided routines. In fact, the time spent on a
  66 longjmp()
  67 will be proportional to the number of call frames
  68 that exist between the points where setjmp()
  69 and
  70 longjmp()
  71 were called. For this reason, the
  72 unwind\-setjmp
  73 library is beneficial primarily in applications
  74 that frequently call setjmp()
  75 but only rarely call
  76 longjmp().
  77 .PP
  78 .SH CAVEATS
  79
  80 .PP
  81 .TP
  82 .B *
  83 The correct operation of this library depends on the presence of
  84 correct unwind information. On newer platforms, this is rarely an
  85 issue. On older platforms, care needs to be taken to
  86 ensure that each of the functions whose stack frames may have to be
  87 unwound during a longjmp()
  88 have correct unwind information
  89 (on those platforms, there is usually a compiler\-switch, such as
  90 \fB\-funwind\-tables\fP,
  91 to request the generation of unwind
  92 information).
  93 .TP
  94 .B *
  95 The contents of jmp_buf and sigjmp_buf as setup
  96 and used by these routines is completely different from the ones
  97 used by the system\-provided routines. Thus, a jump\-buffer created
  98 by the libunwind\-based setjmp()/_setjmp
  99 may only be
 100 used in a call to the libunwind\-based
 101 longjmp()/_longjmp().
 102 The analogous applies for
 103 sigjmp_buf
 104 with sigsetjmp()
 105 and siglongjmp().
 106 .PP
 107 .SH FILES
 108
 109 .PP
 110 .TP
 111 \fB\-l\fPunwind\-setjmp
 112  The library an application should
 113 be linked against to ensure it uses the libunwind\-based non\-local
 114 goto routines.
 115 .PP
 116 .SH SEE ALSO
 117
 118 .PP
 119 libunwind(3),
 120 setjmp(3), longjmp(3),
 121 _setjmp(3), _longjmp(3),
 122 sigsetjmp(3), siglongjmp(3)
 123 .PP
 124 .SH AUTHOR
 125
 126 .PP
 127 David Mosberger\-Tang
 128 .br
 129 Email: \fBdmosberger@gmail.com\fP
 130 .br
 131 WWW: \fBhttp://www.nongnu.org/libunwind/\fP\&.
 132 .\" NOTE: This file is generated, DO NOT EDIT.