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 2014-01-07 "" "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
  57 .I env
  58 for
  59 later use by
  60 .BR longjmp (3).
  61 The stack context will be invalidated
  62 if the function which called
  63 .BR setjmp ()
  64 returns.
  65 .P
  66 .BR sigsetjmp ()
  67 is similar to
  68 .BR setjmp ().
  69 If, and only if,
  70 .I savesigs
  71 is nonzero,
  72 the process's current signal mask is saved in
  73 .I env
  74 and will be restored if a
  75 .BR siglongjmp (3)
  76 is later performed with this
  77 .IR env .
  78 .SH RETURN VALUE
  79 .BR setjmp ()
  80 and
  81 .BR sigsetjmp ()
  82 return 0 if returning directly, and
  83 nonzero when returning from
  84 .BR longjmp (3)
  85 or
  86 .BR siglongjmp (3)
  87 using the saved context.
  88 .SH CONFORMING TO
  89 C89, C99, and POSIX.1-2001 specify
  90 .BR setjmp ().
  91 POSIX.1-2001 specifies
  92 .BR sigsetjmp ().
  93 .SH NOTES
  94 POSIX does not specify whether
  95 .BR setjmp ()
  96 will save the signal mask
  97 (to be later restored during
  98 .BR longjmp (3)).
  99 In System V it will not.
 100 In 4.3BSD it will, and there
 101 is a function
 102 .B _setjmp
 103 that will not.
 104 On Linux with glibc versions before 2.19,
 105 .BR setjmp ()
 106 follows the System V behavior by default,
 107 but the BSD behavior is provided if the
 108 .BR _BSD_SOURCE
 109 feature test macro is defined and none of
 110 .BR _POSIX_SOURCE ,
 111 .BR _POSIX_C_SOURCE ,
 112 .BR _XOPEN_SOURCE ,
 113 .BR _XOPEN_SOURCE_EXTENDED ,
 114 .BR _GNU_SOURCE ,
 115 or
 116 .B _SVID_SOURCE
 117 is defined.
 118 Since glibc 2.19,
 119 .IR <setjmp.h>
 120 exposes only the System V version of
 121 .BR setjmp ().
 122 Programs that need the BSD semantics should replace calls to
 123 .BR setjmp ()
 124 with calls to
 125 .BR sigsetjmp ()
 126 with a nonzero
 127 .I savesigs
 128 argument.
 129
 130 If you want to portably save and restore signal masks, use
 131 .BR sigsetjmp ()
 132 and
 133 .BR siglongjmp (3).
 134 .P
 135 .BR setjmp ()
 136 and
 137 .BR sigsetjmp ()
 138 make programs hard to understand
 139 and maintain.
 140 If possible, an alternative should be used.
 141 .SH SEE ALSO
 142 .BR longjmp (3),
 143 .BR siglongjmp (3)
 144 .SH COLOPHON
 145 This page is part of release 3.67 of the Linux
 146 .I man-pages
 147 project.
 148 A description of the project,
 149 information about reporting bugs,
 150 and the latest version of this page,
 151 can be found at
 152 \%http://www.kernel.org/doc/man\-pages/.