1.\" $NetBSD: setjmp.3,v 1.16 2004/03/30 13:28:13 wiz 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 August 10, 2002 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 67The 68.Fn sigsetjmp , 69.Fn setjmp , 70and 71.Fn _setjmp 72functions save their calling environment in 73.Fa env . 74Each of these functions returns 0. 75.Pp 76The corresponding 77.Fn longjmp 78functions restore the environment saved by the most recent 79invocation of the respective 80.Fn setjmp 81function. 82They then return so that program execution continues as if the corresponding 83invocation of the 84.Fn setjmp 85call had just returned the value specified by 86.Fa val , 87instead of 0. 88.Pp 89Pairs of calls may be intermixed, i.e., both 90.Fn sigsetjmp 91and 92.Fn siglongjmp 93as well as 94.Fn setjmp 95and 96.Fn longjmp 97combinations may be used in the same program. 98However, individual calls may not, e.g., the 99.Fa env 100argument to 101.Fn setjmp 102may not be passed to 103.Fn siglongjmp . 104.Pp 105The 106.Fn longjmp 107routines may not be called after the routine which called the 108.Fn setjmp 109routines returns. 110.Pp 111All accessible objects have values as of the time 112.Fn longjmp 113routine was called, except that the values of objects of automatic storage 114invocation duration that do not have the 115.Li volatile 116type and have been changed between the 117.Fn setjmp 118invocation and 119.Fn longjmp 120call are indeterminate. 121.Pp 122The 123.Fn setjmp Ns / Ns Fn longjmp 124function pairs save and restore the signal mask while 125.Fn _setjmp Ns / Ns Fn _longjmp 126function pairs save and restore only the register set and the stack. 127(See 128.Fn sigmask 2 . ) 129.Pp 130The 131.Fn sigsetjmp Ns / Ns Fn siglongjmp 132function pairs save and restore the signal mask if the argument 133.Fa savemask 134is non-zero. 135Otherwise, only the register set and the stack are saved. 136.Pp 137In other words, 138.Fn setjmp Ns / Ns Fn longjmp 139are functionally equivalent to 140.Fn sigsetjmp Ns / Ns Fn siglongjmp 141when 142.Fn sigsetjmp 143is called with a non-zero 144.Fa savemask 145argument. 146Conversely, 147.Fn _setjmp Ns / Ns Fn _longjmp 148are functionally equivalent to 149.Fn sigsetjmp Ns / Ns Fn siglongjmp 150when 151.Fn sigsetjmp 152is called with a zero-value 153.Fa savemask . 154.Pp 155The 156.Fn sigsetjmp Ns / Ns Fn siglongjmp 157interfaces are preferred for maximum portability. 158.Sh ERRORS 159If the contents of the 160.Fa env 161are corrupted or correspond to an environment that has already returned, 162the 163.Fn longjmp 164routine calls the routine 165.Xr longjmperror 3 . 166If 167.Fn longjmperror 168returns, the program is aborted (see 169.Xr abort 3 ) . 170The default version of 171.Fn longjmperror 172prints the message 173.Dq Li longjmp botch 174to standard error and returns. 175User programs wishing to exit more gracefully should write their own 176versions of 177.Fn longjmperror . 178.Sh SEE ALSO 179.Xr sigaction 2 , 180.Xr sigaltstack 2 , 181.Xr signal 3 182.Sh STANDARDS 183The 184.Fn setjmp 185and 186.Fn longjmp 187functions conform to 188.St -ansiC . 189The 190.Fn sigsetjmp 191and 192.Fn siglongjmp 193functions conform to 194.St -p1003.1-90 . 195.Sh CAVEATS 196Historically, on 197.At V , 198the 199.Fn setjmp Ns / Ns Fn longjmp 200functions have been equivalent to the 201.Bx 202.Fn _setjmp Ns / Ns Fn _longjmp 203functions and do not restore the signal mask. 204Because of this discrepancy, the 205.Fn sigsetjmp Ns / Ns Fn siglongjmp 206interfaces should be used if portability is desired. 207.Pp 208Use of 209.Fn longjmp 210or 211.Fn siglongjmp 212from inside a signal handler is not as easy as it might seem. 213Generally speaking, all possible code paths between the 214.Fn setjmp 215and 216.Fn longjmp 217must be signal race safe. 218Furthermore, the code paths must not do resource management 219(such as 220.Xr open 2 221or 222.Xr close 2 ) 223without blocking the signal in question, or resources might 224be mismanaged. 225Obviously this makes 226.Fn longjmp 227much less useful than previously thought. 228