man/man3/setjmp.3

   1 .TH SETJMP 3    "June 22, 2006"
   2 .UC 4
   3 .SH NAME
   4 setjmp, longjmp, _setjmp, _longjmp, sigsetjmp, siglongjmp \- save and restore execution contexts
   5 .SH SYNOPSIS
   6 .nf
   7 .ft B
   8 #include <setjmp.h>
   9
  10 int setjmp(jmp_buf env);
  11 void longjmp(jmp_buf env, int val);
  12
  13 int _setjmp(jmp_buf env);
  14 void _longjmp(jmp_buf env, int val);
  15
  16 #define _POSIX_SOURCE
  17 int sigsetjmp(sigjmp_buf env, int savemask);
  18 void siglongjmp(sigjmp_buf env, int val);
  19 .SH DESCRIPTION
  20 These calls provide a way for a process to save an execution context into a
  21 buffer, and later resume execution from that context, effectively performing
  22 a non-local jump. The
  23 .B setjmp
  24 family of functions store the context into the \fIenv\fP data structure,
  25 and return the value 0. The
  26 .B longjmp
  27 family of functions jump to the context saved in the given \fIenv\fP data
  28 structure, causing the process to continue as if it returned from the
  29 corresponding
  30 .B setjmp
  31 call again, but this time with the non-zero return value in \fIval\fP.
  32 .PP
  33 The difference between the three pairs of setjmp/longjmp functions lies in the
  34 behaviour with respect to saving/restoring the process signal mask. POSIX does
  35 not require the process signal mask to be saved and restored during
  36 .B setjmp
  37 /
  38 .B longjmp
  39 \. However, the current implementation does this in order to agree with OSF/1
  40 and other BSD derived systems.
  41 .PP
  42 The pair of functions
  43 .B _setjmp
  44 /
  45 .B _longjmp
  46 , traditional in BSD systems, may be used when the signal mask is not to be
  47 saved/restored.
  48 .PP
  49 Finally, the POSIX
  50 .B sigsetjmp
  51 /
  52 .B siglongjmp
  53 functions allow the programmer to specify explicitly whether the signal mask
  54 is to be saved/restored, by means of the \fIsavemask\fP parameter. If this
  55 parameter is zero, the signal mask will not be saved/restored, otherwise it
  56 will.
  57 .SH NOTES
  58 After the function calling
  59 .B setjmp
  60 has returned, the saved context may not be used in a call to
  61 .B longjmp
  62 anymore, since the relevant portion of the stack may already have been wiped
  63 out at that point.
  64 .PP
  65 Using these functions to return to a previous state from a signal handler
  66 is possible but should be done with extreme care, as some interrupted library
  67 routines may not be reentrant and/or temporarily allocate resources.
  68 .PP
  69 See the setjmp.h header file for more implementation details specific to Minix.