original/man3/setjmp.3

   1 .\" Written by Michael Haardt, Fri Nov 25 14:51:42 MET 1994
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_DOC_FULL)
   4 .\" This is free documentation; you can redistribute it and/or
   5 .\" modify it under the terms of the GNU General Public License as
   6 .\" published by the Free Software Foundation; either version 2 of
   7 .\" the License, or (at your option) any later version.
   8 .\"
   9 .\" The GNU General Public License's references to "object code"
  10 .\" and "executables" are to be interpreted as the output of any
  11 .\" document formatting or typesetting system, including
  12 .\" intermediate and printed output.
  13 .\"
  14 .\" This manual is distributed in the hope that it will be useful,
  15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
  16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17 .\" GNU General Public License for more details.
  18 .\"
  19 .\" You should have received a copy of the GNU General Public
  20 .\" License along with this manual; if not, see
  21 .\" <http://www.gnu.org/licenses/>.
  22 .\" %%%LICENSE_END
  23 .\"
  24 .\" Added sigsetjmp, Sun Mar  2 22:03:05 EST 1997, jrv@vanzandt.mv.com
  25 .\" Modifications, Sun Feb 26 14:39:45 1995, faith@cs.unc.edu
  26 .\" "
  27 .TH SETJMP 3 2009-06-26 "" "Linux Programmer's Manual"
  28 .SH NAME
  29 setjmp, sigsetjmp \- save stack context for nonlocal goto
  30 .SH SYNOPSIS
  31 .B #include <setjmp.h>
  32 .sp
  33 .nf
  34 .BI "int setjmp(jmp_buf " env );
  35
  36 .BI "int sigsetjmp(sigjmp_buf " env ", int " savesigs );
  37 .fi
  38 .sp
  39 .in -4n
  40 Feature Test Macro Requirements for glibc (see
  41 .BR feature_test_macros (7)):
  42 .in
  43 .sp
  44 .BR setjmp ():
  45 see NOTES.
  46 .br
  47 .BR sigsetjmp ():
  48 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_C_SOURCE
  49 .SH DESCRIPTION
  50 .BR setjmp ()
  51 and
  52 .BR longjmp (3)
  53 are useful for dealing with errors
  54 and interrupts encountered in a low-level subroutine of a program.
  55 .BR setjmp ()
  56 saves the stack context/environment in \fIenv\fP for
  57 later use by
  58 .BR longjmp (3).
  59 The stack context will be invalidated
  60 if the function which called
  61 .BR setjmp ()
  62 returns.
  63 .P
  64 .BR sigsetjmp ()
  65 is similar to
  66 .BR setjmp ().
  67 If, and only if, \fIsavesigs\fP is nonzero,
  68 the process's current signal mask is saved in \fIenv\fP
  69 and will be restored if a
  70 .BR siglongjmp (3)
  71 is later performed with this \fIenv\fP.
  72 .SH RETURN VALUE
  73 .BR setjmp ()
  74 and
  75 .BR sigsetjmp ()
  76 return 0 if returning directly, and
  77 nonzero when returning from
  78 .BR longjmp (3)
  79 or
  80 .BR siglongjmp (3)
  81 using the saved context.
  82 .SH CONFORMING TO
  83 C89, C99, and POSIX.1-2001 specify
  84 .BR setjmp ().
  85 POSIX.1-2001 specifies
  86 .BR sigsetjmp ().
  87 .SH NOTES
  88 POSIX does not specify whether
  89 .BR setjmp ()
  90 will save the signal mask.
  91 In System V it will not.
  92 In 4.3BSD it will, and there
  93 is a function \fB_setjmp\fP that will not.
  94 By default, Linux/glibc follows the System V behavior,
  95 but the BSD behavior is provided if the
  96 .BR _BSD_SOURCE
  97 feature test macro is defined and none of
  98 .BR _POSIX_SOURCE ,
  99 .BR _POSIX_C_SOURCE ,
 100 .BR _XOPEN_SOURCE ,
 101 .BR _XOPEN_SOURCE_EXTENDED ,
 102 .BR _GNU_SOURCE ,
 103 or
 104 .B _SVID_SOURCE
 105 is defined.
 106
 107 If you want to portably save and restore signal masks, use
 108 .BR sigsetjmp ()
 109 and
 110 .BR siglongjmp (3).
 111 .P
 112 .BR setjmp ()
 113 and
 114 .BR sigsetjmp ()
 115 make programs hard to understand
 116 and maintain.
 117 If possible an alternative should be used.
 118 .SH SEE ALSO
 119 .BR longjmp (3),
 120 .BR siglongjmp (3)