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
25The \Prog{unwind-setjmp} library offers a \Prog{libunwind}-based
26implementation of non-local gotos.  This implementation is intended to
27be a drop-in replacement for the normal, system-provided routines of
28the same name.  The main advantage of using the \Prog{unwind-setjmp}
29library 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
31need to be saved in the jump-buffer (plus one call to
32\Func{sigprocmask}(2), in the case of \Func{sigsetjmp}).  On the
33other hand, executing a non-local goto by calling one of the
34\Func{longjmp}() routines tends to be much slower than with the
35system-provided routines.  In fact, the time spent on a
36\Func{longjmp}() will be proportional to the number of call frames
37that 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
40that 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)},
75setjmp(3), longjmp(3),
76\_setjmp(3), \_longjmp(3),
77sigsetjmp(3), siglongjmp(3)
78
79\section{Author}
80
81\noindent
82David Mosberger-Tang\\
83Email: \Email{dmosberger@gmail.com}\\
84WWW: \URL{http://www.nongnu.org/libunwind/}.
85\LatexManEnd
86
87\end{document}
88