xref: /freebsd/lib/libc/gen/setjmp.3 (revision 8bab661a3316d8bd9b9fbd11a3b4371b91507bd2)
1.\" Copyright (c) 1990, 1991, 1993
2.\"	The Regents of the University of California.  All rights reserved.
3.\"
4.\" This code is derived from software contributed to Berkeley by
5.\" the American National Standards Committee X3, on Information
6.\" Processing Systems.
7.\"
8.\" Redistribution and use in source and binary forms, with or without
9.\" modification, are permitted provided that the following conditions
10.\" are met:
11.\" 1. Redistributions of source code must retain the above copyright
12.\"    notice, this list of conditions and the following disclaimer.
13.\" 2. Redistributions in binary form must reproduce the above copyright
14.\"    notice, this list of conditions and the following disclaimer in the
15.\"    documentation and/or other materials provided with the distribution.
16.\" 3. Neither the name of the University nor the names of its contributors
17.\"    may be used to endorse or promote products derived from this software
18.\"    without specific prior written permission.
19.\"
20.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30.\" SUCH DAMAGE.
31.\"
32.\"     @(#)setjmp.3	8.1 (Berkeley) 6/4/93
33.\" $FreeBSD$
34.\"
35.Dd April 2, 2022
36.Dt SETJMP 3
37.Os
38.Sh NAME
39.Nm sigsetjmp ,
40.Nm siglongjmp ,
41.Nm setjmp ,
42.Nm longjmp ,
43.Nm _setjmp ,
44.Nm _longjmp ,
45.Nm longjmperror
46.Nd non-local jumps
47.Sh LIBRARY
48.Lb libc
49.Sh SYNOPSIS
50.In setjmp.h
51.Ft int
52.Fn sigsetjmp "sigjmp_buf env" "int savemask"
53.Ft void
54.Fn siglongjmp "sigjmp_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.Ft int
60.Fn _setjmp "jmp_buf env"
61.Ft void
62.Fn _longjmp "jmp_buf env" "int val"
63.Ft void
64.Fn longjmperror void
65.Sh DESCRIPTION
66The
67.Fn sigsetjmp ,
68.Fn setjmp ,
69and
70.Fn _setjmp
71functions save their calling environment in
72.Fa env .
73Each of these functions returns 0.
74.Pp
75The corresponding
76.Fn longjmp
77functions restore the environment saved by their most recent respective
78invocations
79of the
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
93and
94.Fn setjmp
95and
96.Fn longjmp
97combinations may be used in the same program, however, individual
98calls 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.Vt 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
124pairs save and restore the signal mask while
125.Fn _setjmp Ns / Ns Fn _longjmp
126pairs 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
133pairs save and restore the signal mask if the argument
134.Fa savemask
135is non-zero, otherwise only the register set and the stack are saved.
136.Sh ERRORS
137If the contents of the
138.Fa env
139are corrupted, or correspond to an environment that has already returned,
140the
141.Fn longjmp
142routine calls the routine
143.Fn longjmperror 3 .
144If
145.Fn longjmperror
146returns the program is aborted (see
147.Xr abort 3 ) .
148The default version of
149.Fn longjmperror
150prints the message
151.Dq Li longjmp botch
152to standard error and returns.
153User programs wishing to exit more gracefully should write their own
154versions of
155.Fn longjmperror .
156.Sh SEE ALSO
157.Xr sigaction 2 ,
158.Xr sigaltstack 2 ,
159.Xr signal 3
160.Sh STANDARDS
161The
162.Fn setjmp
163and
164.Fn longjmp
165functions conform to
166.St -isoC .
167The
168.Fn sigsetjmp
169and
170.Fn siglongjmp
171functions conform to
172.St -p1003.1-88 .
173.Sh HISTORY
174The
175.Fn setjmp
176and
177.Fn longjmp
178functions first appeared in the Programmer's Workbench (PWB/UNIX).
179