doc/libunwind-setjmp.tex

   1 \documentclass{article}
   2 \usepackage[fancyhdr,pdf]{latex2man}
   3
   4 \input{common.tex}
   5
   6 \begin{document}
   7
   8 \begin{Name}{3}{libunwind-setjmp}{David Mosberger-Tang}{Programming Library}{libunwind-based non-local gotos}libunwind-setjmp -- libunwind-based non-local gotos
   9 \end{Name}
  10
  11 \section{Synopsis}
  12
  13 \File{\#include $<$setjmp.h$>$}\\
  14
  15 \noindent
  16 \Type{int} \Func{setjmp}(\Type{jmp\_buf}~\Var{env});\\
  17 \Type{void} \Func{longjmp}(\Type{jmp\_buf}~\Var{env}, \Type{int}~\Var{val});\\
  18 \Type{int} \Func{\_setjmp}(\Type{jmp\_buf}~\Var{env});\\
  19 \Type{void} \Func{\_longjmp}(\Type{jmp\_buf}~\Var{env}, \Type{int}~\Var{val});\\
  20 \Type{int} \Func{sigsetjmp}(\Type{sigjmp\_buf}~\Var{env}, \Type{int}~\Var{savemask});\\
  21 \Type{void} \Func{siglongjmp}(\Type{sigjmp\_buf}~\Var{env}, \Type{int}~\Var{val});\\
  22
  23 \section{Description}
  24
  25 The \Prog{unwind-setjmp} library offers a \Prog{libunwind}-based
  26 implementation of non-local gotos.  This implementation is intended to
  27 be a drop-in replacement for the normal, system-provided routines of
  28 the same name.  The main advantage of using the \Prog{unwind-setjmp}
  29 library is that setting up a non-local goto via one of the
  30 \Func{setjmp}() routines is very fast.  Typically, just 2 or 3 words
  31 need to be saved in the jump-buffer (plus one call to
  32 \Func{sigprocmask}(2), in the case of \Func{sigsetjmp}).  On the
  33 other hand, executing a non-local goto by calling one of the
  34 \Func{longjmp}() routines tends to be much slower than with the
  35 system-provided routines.  In fact, the time spent on a
  36 \Func{longjmp}() will be proportional to the number of call frames
  37 that exist between the points where \Func{setjmp}() and
  38 \Func{longjmp}() were called.  For this reason, the
  39 \Prog{unwind-setjmp} library is beneficial primarily in applications
  40 that frequently call \Func{setjmp}() but only rarely call
  41 \Func{longjmp}().
  42
  43 \section{Caveats}
  44
  45 \begin{itemize}
  46 \item The correct operation of this library depends on the presence of
  47   correct unwind information.  On newer platforms, this is rarely an
  48   issue.  On older platforms, care needs to be taken to
  49   ensure that each of the functions whose stack frames may have to be
  50   unwound during a \Func{longjmp}() have correct unwind information
  51   (on those platforms, there is usually a compiler-switch, such as
  52   \Opt{-funwind-tables}, to request the generation of unwind
  53   information).
  54 \item The contents of \Type{jmp\_buf} and \Type{sigjmp\_buf} as setup
  55   and used by these routines is completely different from the ones
  56   used by the system-provided routines.  Thus, a jump-buffer created
  57   by the libunwind-based \Func{setjmp}()/\Func{\_setjmp} may only be
  58   used in a call to the libunwind-based
  59   \Func{longjmp}()/\Func{\_longjmp}().  The analogous applies for
  60   \Type{sigjmp\_buf} with \Func{sigsetjmp}() and \Func{siglongjmp}().
  61 \end{itemize}
  62
  63 \section{Files}
  64
  65 \begin{Description}
  66 \item[\Opt{-l}\File{unwind-setjmp}] The library an application should
  67   be linked against to ensure it uses the libunwind-based non-local
  68   goto routines.
  69 \end{Description}
  70
  71
  72 \section{See Also}
  73
  74 \SeeAlso{libunwind(3)},
  75 setjmp(3), longjmp(3),
  76 \_setjmp(3), \_longjmp(3),
  77 sigsetjmp(3), siglongjmp(3)
  78
  79 \section{Author}
  80
  81 \noindent
  82 David Mosberger-Tang\\
  83 Email: \Email{dmosberger@gmail.com}\\
  84 WWW: \URL{http://www.nongnu.org/libunwind/}.
  85 \LatexManEnd
  86
  87 \end{document}