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