1.\" $OpenBSD: setjmp.3,v 1.25 2016/05/23 00:18:56 guenther 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.Dd $Mdocdate: May 23 2016 $ 35.Dt SETJMP 3 36.Os 37.Sh NAME 38.Nm sigsetjmp , 39.Nm siglongjmp , 40.Nm setjmp , 41.Nm longjmp , 42.Nm _setjmp , 43.Nm _longjmp 44.Nd non-local jumps 45.Sh SYNOPSIS 46.In setjmp.h 47.Ft int 48.Fn sigsetjmp "sigjmp_buf env" "int savemask" 49.Ft void 50.Fn siglongjmp "sigjmp_buf env" "int val" 51.Ft int 52.Fn setjmp "jmp_buf env" 53.Ft void 54.Fn longjmp "jmp_buf env" "int val" 55.Ft int 56.Fn _setjmp "jmp_buf env" 57.Ft void 58.Fn _longjmp "jmp_buf env" "int val" 59.Sh DESCRIPTION 60The 61.Fn sigsetjmp , 62.Fn setjmp , 63and 64.Fn _setjmp 65functions save their calling environment in 66.Fa env . 67Each of these functions returns 0. 68.Pp 69The corresponding 70.Fn longjmp 71functions restore the environment saved by the most recent 72invocation of the respective 73.Fn setjmp 74function. 75They then return so that program execution continues as if the corresponding 76invocation of the 77.Fn setjmp 78call had just returned the value specified by 79.Fa val , 80instead of 0. 81The value specified by 82.Fa val 83must be non-zero; a 0 value is treated as 1 to allow the programmer 84to differentiate between a direct invocation of 85.Fn setjmp 86and a return via 87.Fn longjmp . 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 the 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 the 125.Fn _setjmp Ns / Ns Fn _longjmp 126function pairs save and restore only the register set and the stack (see 127.Xr sigprocmask 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 SEE ALSO 158.Xr sigprocmask 2 159.Sh STANDARDS 160The 161.Fn setjmp 162and 163.Fn longjmp 164functions conform to 165.St -ansiC . 166The 167.Fn sigsetjmp 168and 169.Fn siglongjmp 170functions conform to 171.St -p1003.1-90 . 172.Sh HISTORY 173The 174.Fn setjmp 175and 176.Fn longjmp 177functions first appeared in the Programmer's Workbench (PWB/UNIX). 178.Sh CAVEATS 179Historically, on 180.At V , 181the 182.Fn setjmp Ns / Ns Fn longjmp 183functions have been equivalent to the 184.Bx 185.Fn _setjmp Ns / Ns Fn _longjmp 186functions and do not restore the signal mask. 187Because of this discrepancy, the 188.Fn sigsetjmp Ns / Ns Fn siglongjmp 189interfaces should be used if portability is desired. 190.Pp 191Use of 192.Fn longjmp 193or 194.Fn siglongjmp 195from inside a signal handler is not as easy as it might seem. 196Generally speaking, all possible code paths between the 197.Fn setjmp 198and 199.Fn longjmp 200must be signal race safe, as discussed in 201.Xr signal 3 . 202Furthermore, the code paths must not do resource management 203(such as 204.Xr open 2 205or 206.Xr close 2 ) 207without blocking the signal in question, or resources might 208be mismanaged. 209Obviously this makes 210.Fn longjmp 211much less useful than previously thought. 212