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