NAME

       libunwind-setjmp -- libunwind-based non-local gotos

SYNOPSIS

       #include <setjmp.h>

       int setjmp(jmp_buf env);
       void longjmp(jmp_buf env, int val);
       int _setjmp(jmp_buf env);
       void _longjmp(jmp_buf env, int val);
       int sigsetjmp(sigjmp_buf env, int savemask);
       void siglongjmp(sigjmp_buf env, int val);

DESCRIPTION

       The unwind-setjmp library offers a libunwind-based implementation of non-local gotos. This implementation
       is intended to be a drop-in replacement for the normal, system-provided routines of the  same  name.  The
       main  advantage  of  using  the  unwind-setjmp library is that setting up a non-local goto via one of the
       setjmp() routines is very fast. Typically, just 2 or 3 words need to be saved in  the  jump-buffer  (plus
       one  call to sigprocmask(2), in the case of sigsetjmp).  On the other hand, executing a non-local goto by
       calling one of the longjmp() routines tends to be much slower than with the system-provided routines.  In
       fact,  the time spent on a longjmp() will be proportional to the number of call frames that exist between
       the points where setjmp() and longjmp() were called.  For  this  reason,  the  unwind-setjmp  library  is
       beneficial primarily in applications that frequently call setjmp() but only rarely call longjmp().

CAVEATS

       *      The  correct  operation  of this library depends on the presence of correct unwind information. On
              newer platforms, this is rarely an issue. On older platforms, care needs to  be  taken  to  ensure
              that  each  of  the  functions  whose  stack frames may have to be unwound during a longjmp() have
              correct unwind information (on those platforms,  there  is  usually  a  compiler-switch,  such  as
              -funwind-tables, to request the generation of unwind information).

       *      The contents of jmp_buf and sigjmp_buf as setup and used by these routines is completely different
              from the  ones  used  by  the  system-provided  routines.  Thus,  a  jump-buffer  created  by  the
              libunwind-based   setjmp()/_setjmp   may   only   be   used  in  a  call  to  the  libunwind-based
              longjmp()/_longjmp().  The analogous applies for sigjmp_buf with sigsetjmp() and siglongjmp().

FILES

       -lunwind-setjmp
               The library an application should be  linked  against  to  ensure  it  uses  the  libunwind-based
              non-local goto routines.

SEE ALSO

       libunwind(3), setjmp(3), longjmp(3), _setjmp(3), _longjmp(3), sigsetjmp(3), siglongjmp(3)

AUTHOR

       David Mosberger-Tang
       Email: dmosberger@gmail.com
       WWW: http://www.nongnu.org/libunwind/.