manual/LDP_man-pages/original/man3/setjmp.3

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