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 (a] gmail.com}\\ 84 WWW: \URL{http://www.nongnu.org/libunwind/}. 85 \LatexManEnd 86 87 \end{document} 88
