original/man3/longjmp.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 siglongjmp, 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 LONGJMP 3 2009-01-13 "" "Linux Programmer's Manual"
  28 .SH NAME
  29 longjmp, siglongjmp \- nonlocal jump to a saved stack context
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <setjmp.h>
  33
  34 .BI "void longjmp(jmp_buf " env ", int " val );
  35
  36 .BI "void siglongjmp(sigjmp_buf " env ", int " val );
  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 siglongjmp ():
  45 _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_C_SOURCE
  46 .SH DESCRIPTION
  47 .BR longjmp ()
  48 and
  49 .BR setjmp (3)
  50 are useful for dealing with errors
  51 and interrupts encountered in a low-level subroutine of a program.
  52 .BR longjmp ()
  53 restores the environment saved by the last call of
  54 .BR setjmp (3)
  55 with the corresponding
  56 .I env
  57 argument.
  58 After
  59 .BR longjmp ()
  60 is completed, program execution continues as if the
  61 corresponding call of
  62 .BR setjmp (3)
  63 had just returned the value
  64 .IR val .
  65 .BR longjmp ()
  66 cannot cause 0 to be returned.
  67 If
  68 .BR longjmp ()
  69 is invoked with a second argument of 0, 1 will be returned instead.
  70 .P
  71 .BR siglongjmp ()
  72 is similar to
  73 .BR longjmp ()
  74 except for the type of
  75 its
  76 .I env
  77 argument.
  78 If, and only if, the
  79 .BR sigsetjmp (3)
  80 call that set this
  81 .I env
  82 used a nonzero
  83 .I savesigs
  84 flag,
  85 .BR siglongjmp ()
  86 also restores the signal mask that was saved by
  87 .BR sigsetjmp (3).
  88 .SH RETURN VALUE
  89 These functions never return.
  90 .SH CONFORMING TO
  91 C89, C99, and POSIX.1-2001 specify
  92 .BR longjmp ().
  93 POSIX.1-2001 specifies
  94 .BR siglongjmp ().
  95 .SH NOTES
  96 POSIX does not specify whether
  97 .BR longjmp ()
  98 will restore the signal context (see
  99 .BR setjmp (3)
 100 for some more details).
 101 If you want to portably save and restore signal masks, use
 102 .BR sigsetjmp (3)
 103 and
 104 .BR siglongjmp ().
 105 .P
 106 The values of automatic variables are unspecified after a call to
 107 .BR longjmp ()
 108 if they meet all the following criteria:
 109 .IP \(bu 3
 110 they are local to the function that made the corresponding
 111 .BR setjmp (3)
 112 call;
 113 .IP \(bu
 114 their values are changed between the calls to
 115 .BR setjmp (3)
 116 and
 117 .BR longjmp ();
 118 and
 119 .IP \(bu
 120 they are not declared as
 121 .IR volatile .
 122 .P
 123 Analogous remarks apply for
 124 .BR siglongjmp ().
 125 .P
 126 .BR longjmp ()
 127 and
 128 .BR siglongjmp ()
 129 make programs hard to
 130 understand and maintain.
 131 If possible, an alternative should be used.
 132 .SH SEE ALSO
 133 .BR setjmp (3),
 134 .BR sigsetjmp (3)
 135 .SH COLOPHON
 136 This page is part of release 3.67 of the Linux
 137 .I man-pages
 138 project.
 139 A description of the project,
 140 information about reporting bugs,
 141 and the latest version of this page,
 142 can be found at
 143 \%http://www.kernel.org/doc/man\-pages/.