1.\"	$NetBSD: setjmp.3,v 1.17 2008/05/31 16:15:07 enami 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 June 1, 2008
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 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, 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.
127(See
128.Fn sigprocmask 2 . )
129.Pp
130The
131.Fn sigsetjmp Ns / Ns Fn siglongjmp
132function pairs save and restore the signal mask if the argument
133.Fa savemask
134is non-zero.
135Otherwise, only the register set and the stack are saved.
136.Pp
137In other words,
138.Fn setjmp Ns / Ns Fn longjmp
139are functionally equivalent to
140.Fn sigsetjmp Ns / Ns Fn siglongjmp
141when
142.Fn sigsetjmp
143is called with a non-zero
144.Fa savemask
145argument.
146Conversely,
147.Fn _setjmp Ns / Ns Fn _longjmp
148are functionally equivalent to
149.Fn sigsetjmp Ns / Ns Fn siglongjmp
150when
151.Fn sigsetjmp
152is called with a zero-value
153.Fa savemask .
154.Pp
155The
156.Fn sigsetjmp Ns / Ns Fn siglongjmp
157interfaces are preferred for maximum portability.
158.Sh ERRORS
159If the contents of the
160.Fa env
161are corrupted or correspond to an environment that has already returned,
162the
163.Fn longjmp
164routine calls the routine
165.Xr longjmperror 3 .
166If
167.Fn longjmperror
168returns, the program is aborted (see
169.Xr abort 3 ) .
170The default version of
171.Fn longjmperror
172prints the message
173.Dq Li longjmp botch
174to standard error and returns.
175User programs wishing to exit more gracefully should write their own
176versions of
177.Fn longjmperror .
178.Sh SEE ALSO
179.Xr sigaction 2 ,
180.Xr sigaltstack 2 ,
181.Xr sigprocmask 2 ,
182.Xr pthread_sigmask 3 ,
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