lib/libc/gen/setjmp.3

   1 .\"     $NetBSD: setjmp.3,v 1.17 2008/05/31 16:15:07 enami Exp $
   2 .\"
   3 .\" Copyright (c) 1990, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to Berkeley by
   7 .\" the American National Standards Committee X3, on Information
   8 .\" Processing Systems.
   9 .\"
  10 .\" Redistribution and use in source and binary forms, with or without
  11 .\" modification, are permitted provided that the following conditions
  12 .\" are met:
  13 .\" 1. Redistributions of source code must retain the above copyright
  14 .\"    notice, this list of conditions and the following disclaimer.
  15 .\" 2. Redistributions in binary form must reproduce the above copyright
  16 .\"    notice, this list of conditions and the following disclaimer in the
  17 .\"    documentation and/or other materials provided with the distribution.
  18 .\" 3. Neither the name of the University nor the names of its contributors
  19 .\"    may be used to endorse or promote products derived from this software
  20 .\"    without specific prior written permission.
  21 .\"
  22 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  25 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  32 .\" SUCH DAMAGE.
  33 .\"
  34 .\"     @(#)setjmp.3    8.1 (Berkeley) 6/4/93
  35 .\"
  36 .Dd June 1, 2008
  37 .Dt SETJMP 3
  38 .Os
  39 .Sh NAME
  40 .Nm sigsetjmp ,
  41 .Nm siglongjmp ,
  42 .Nm setjmp ,
  43 .Nm longjmp ,
  44 .Nm _setjmp ,
  45 .Nm _longjmp ,
  46 .Nm longjmperror
  47 .Nd non-local jumps
  48 .Sh LIBRARY
  49 .Lb libc
  50 .Sh SYNOPSIS
  51 .In setjmp.h
  52 .Ft int
  53 .Fn sigsetjmp "sigjmp_buf env" "int savemask"
  54 .Ft void
  55 .Fn siglongjmp "sigjmp_buf env" "int val"
  56 .Ft int
  57 .Fn setjmp "jmp_buf env"
  58 .Ft void
  59 .Fn longjmp "jmp_buf env" "int val"
  60 .Ft int
  61 .Fn _setjmp "jmp_buf env"
  62 .Ft void
  63 .Fn _longjmp "jmp_buf env" "int val"
  64 .Ft void
  65 .Fn longjmperror void
  66 .Sh DESCRIPTION
  67 The
  68 .Fn sigsetjmp ,
  69 .Fn setjmp ,
  70 and
  71 .Fn _setjmp
  72 functions save their calling environment in
  73 .Fa env .
  74 Each of these functions returns 0.
  75 .Pp
  76 The corresponding
  77 .Fn longjmp
  78 functions restore the environment saved by the most recent
  79 invocation of the respective
  80 .Fn setjmp
  81 function.
  82 They then return so that program execution continues as if the corresponding
  83 invocation of the
  84 .Fn setjmp
  85 call had just returned the value specified by
  86 .Fa val ,
  87 instead of 0.
  88 .Pp
  89 Pairs of calls may be intermixed, i.e., both
  90 .Fn sigsetjmp
  91 and
  92 .Fn siglongjmp
  93 as well as
  94 .Fn setjmp
  95 and
  96 .Fn longjmp
  97 combinations may be used in the same program.
  98 However, individual calls may not, e.g., the
  99 .Fa env
 100 argument to
 101 .Fn setjmp
 102 may not be passed to
 103 .Fn siglongjmp .
 104 .Pp
 105 The
 106 .Fn longjmp
 107 routines may not be called after the routine which called the
 108 .Fn setjmp
 109 routines returns.
 110 .Pp
 111 All accessible objects have values as of the time
 112 .Fn longjmp
 113 routine was called, except that the values of objects of automatic storage
 114 invocation duration that do not have the
 115 .Li volatile
 116 type and have been changed between the
 117 .Fn setjmp
 118 invocation and
 119 .Fn longjmp
 120 call are indeterminate.
 121 .Pp
 122 The
 123 .Fn setjmp Ns / Ns Fn longjmp
 124 function pairs save and restore the signal mask while
 125 .Fn _setjmp Ns / Ns Fn _longjmp
 126 function pairs save and restore only the register set and the stack.
 127 (See
 128 .Fn sigprocmask 2 . )
 129 .Pp
 130 The
 131 .Fn sigsetjmp Ns / Ns Fn siglongjmp
 132 function pairs save and restore the signal mask if the argument
 133 .Fa savemask
 134 is non-zero.
 135 Otherwise, only the register set and the stack are saved.
 136 .Pp
 137 In other words,
 138 .Fn setjmp Ns / Ns Fn longjmp
 139 are functionally equivalent to
 140 .Fn sigsetjmp Ns / Ns Fn siglongjmp
 141 when
 142 .Fn sigsetjmp
 143 is called with a non-zero
 144 .Fa savemask
 145 argument.
 146 Conversely,
 147 .Fn _setjmp Ns / Ns Fn _longjmp
 148 are functionally equivalent to
 149 .Fn sigsetjmp Ns / Ns Fn siglongjmp
 150 when
 151 .Fn sigsetjmp
 152 is called with a zero-value
 153 .Fa savemask .
 154 .Pp
 155 The
 156 .Fn sigsetjmp Ns / Ns Fn siglongjmp
 157 interfaces are preferred for maximum portability.
 158 .Sh ERRORS
 159 If the contents of the
 160 .Fa env
 161 are corrupted or correspond to an environment that has already returned,
 162 the
 163 .Fn longjmp
 164 routine calls the routine
 165 .Xr longjmperror 3 .
 166 If
 167 .Fn longjmperror
 168 returns, the program is aborted (see
 169 .Xr abort 3 ) .
 170 The default version of
 171 .Fn longjmperror
 172 prints the message
 173 .Dq Li longjmp botch
 174 to standard error and returns.
 175 User programs wishing to exit more gracefully should write their own
 176 versions of
 177 .Fn longjmperror .
 178 .Sh SEE ALSO
 179 .Xr sigaction 2 ,
 180 .Xr sigaltstack 2 ,
 181 .Xr sigprocmask 2 ,
 182 .Xr pthread_sigmask 3 ,
 183 .Xr signal 3
 184 .Sh STANDARDS
 185 The
 186 .Fn setjmp
 187 and
 188 .Fn longjmp
 189 functions conform to
 190 .St -ansiC .
 191 The
 192 .Fn sigsetjmp
 193 and
 194 .Fn siglongjmp
 195 functions conform to
 196 .St -p1003.1-90 .
 197 .Sh CAVEATS
 198 Historically, on
 199 .At V ,
 200 the
 201 .Fn setjmp Ns / Ns Fn longjmp
 202 functions have been equivalent to the
 203 .Bx
 204 .Fn _setjmp Ns / Ns Fn _longjmp
 205 functions and do not restore the signal mask.
 206 Because of this discrepancy, the
 207 .Fn sigsetjmp Ns / Ns Fn siglongjmp
 208 interfaces should be used if portability is desired.
 209 .Pp
 210 Use of
 211 .Fn longjmp
 212 or
 213 .Fn siglongjmp
 214 from inside a signal handler is not as easy as it might seem.
 215 Generally speaking, all possible code paths between the
 216 .Fn setjmp
 217 and
 218 .Fn longjmp
 219 must be signal race safe.
 220 Furthermore, the code paths must not do resource management
 221 (such as
 222 .Xr open 2
 223 or
 224 .Xr close 2 )
 225 without blocking the signal in question, or resources might
 226 be mismanaged.
 227 Obviously this makes
 228 .Fn longjmp
 229 much less useful than previously thought.