1.\" $OpenBSD: setjmp.3,v 1.12 2001/01/12 21:28:19 millert 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. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgement: 20.\" This product includes software developed by the University of 21.\" California, Berkeley and its contributors. 22.\" 4. Neither the name of the University nor the names of its contributors 23.\" may be used to endorse or promote products derived from this software 24.\" without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 27.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 28.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 29.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 30.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 31.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 32.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 33.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 34.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 35.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 36.\" SUCH DAMAGE. 37.\" 38.Dd June 4, 1993 39.Dt SETJMP 3 40.Os 41.Sh NAME 42.Nm sigsetjmp , 43.Nm siglongjmp , 44.Nm setjmp , 45.Nm longjmp , 46.Nm _setjmp , 47.Nm _longjmp , 48.Nm longjmperror 49.Nd non-local jumps 50.Sh SYNOPSIS 51.Fd #include <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 \(em 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 (see 127.Xr sigmask 2 ) . 128.Pp 129The 130.Fn sigsetjmp Ns / Ns Fn siglongjmp 131function pairs save and restore the signal mask if the argument 132.Fa savemask 133is non-zero. 134Otherwise, only the register set and the stack are saved. 135.Pp 136In other words, 137.Fn setjmp Ns / Ns Fn longjmp 138are functionally equivalent to 139.Fn sigsetjmp Ns / Ns Fn siglongjmp 140when 141.Fn sigsetjmp 142is called with a non-zero 143.Fa savemask 144argument. 145Conversely, 146.Fn _setjmp Ns / Ns Fn _longjmp 147are functionally equivalent to 148.Fn sigsetjmp Ns / Ns Fn siglongjmp 149when 150.Fn sigsetjmp 151is called with a zero-value 152.Fa savemask . 153.Pp 154The 155.Fn sigsetjmp Ns / Ns Fn siglongjmp 156interfaces are preferred for maximum portability. 157.Sh ERRORS 158If the contents of the 159.Fa env 160are corrupted or correspond to an environment that has already returned, 161the 162.Fn longjmp 163routine calls the routine 164.Fn longjmperror 3 . 165If 166.Fn longjmperror 167returns the program is aborted (see 168.Xr abort 3 ) . 169The default version of 170.Fn longjmperror 171prints the message 172.Dq Li longjmp botch 173to standard error and returns. 174User programs wishing to exit more gracefully should write their own 175versions of 176.Fn longjmperror . 177.Sh SEE ALSO 178.Xr sigaction 2 , 179.Xr sigaltstack 2 , 180.Xr signal 3 181.Sh STANDARDS 182The 183.Fn setjmp 184and 185.Fn longjmp 186functions conform to 187.St -ansiC . 188The 189.Fn sigsetjmp 190and 191.Fn siglongjmp 192functions conform to 193.St -p1003.1-90 . 194.Sh CAVEATS 195Historically, on 196.At V , 197the 198.Fn setjmp Ns / Ns Fn longjmp 199functions have been equivalent to the 200.Bx 201.Fn _setjmp Ns / Ns Fn _longjmp 202functions and do not restore the signal mask. 203Because of this discrepancy, the 204.Fn sigsetjmp Ns / Ns Fn siglongjmp 205interfaces should be used if portability is desired. 206