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