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