[apple/libplatform.git] / man / setjmp.3

.\" Copyright (c) 1990, 1991, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" This code is derived from software contributed to Berkeley by
.\" the American National Standards Committee X3, on Information
.\" Processing Systems.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\"    must display the following acknowledgement:
.\"	This product includes software developed by the University of
.\"	California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"     @(#)setjmp.3	8.1 (Berkeley) 6/4/93
.\" $FreeBSD: src/lib/libc/gen/setjmp.3,v 1.9 2001/10/01 16:08:51 ru Exp $
.\"
.Dd June 4, 1993
.Dt SETJMP 3
.Os
.Sh NAME
.Nm _longjmp ,
.Nm _setjmp ,
.Nm longjmp ,
.Nm longjmperror ,
.Nm setjmp ,
.Nm siglongjmp ,
.Nm sigsetjmp
.Nd non-local jumps
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In setjmp.h
.Ft void
.Fo _longjmp
.Fa "jmp_buf env"
.Fa "int val"
.Fc
.Ft int
.Fo _setjmp
.Fa "jmp_buf env"
.Fc
.Ft void
.Fo longjmp
.Fa "jmp_buf env"
.Fa "int val"
.Fc
.Ft void
.Fo longjmperror
.Fa void
.Fc
.Ft int
.Fo setjmp
.Fa "jmp_buf env"
.Fc
.Ft void
.Fo siglongjmp
.Fa "sigjmp_buf env"
.Fa "int val"
.Fc
.Ft int
.Fo sigsetjmp
.Fa "sigjmp_buf env"
.Fa "int savemask"
.Fc
.Sh DESCRIPTION
The
.Fn sigsetjmp ,
.Fn setjmp ,
and
.Fn _setjmp
functions save their calling environment in
.Fa env .
Each of these functions returns 0.
.Pp
The corresponding
.Fn longjmp
functions restore the environment saved by their most recent respective
invocations
of the
.Fn setjmp
function.
They then return, so that program execution continues
as if the corresponding invocation of the
.Fn setjmp
call had just returned the value specified by
.Fa val ,
instead of 0.
.Pp
Pairs of calls may be intermixed
(i.e., both
.Fn sigsetjmp
and
.Fn siglongjmp
and
.Fn setjmp
and
.Fn longjmp
combinations may be used in the same program); however, individual
calls may not (e.g. the
.Fa env
argument to
.Fn setjmp
may not be passed to
.Fn siglongjmp ) .
.Pp
The
.Fn longjmp
routines may not be called after the routine which called the
.Fn setjmp
routines returns.
.Pp
All accessible objects have values as of the time
.Fn longjmp
routine was called, except that the values of objects of automatic storage
invocation duration that do not have the
.Em volatile
type and have been changed between the
.Fn setjmp
invocation and
.Fn longjmp
call are indeterminate.
.Pp
The
.Fn setjmp Ns / Ns Fn longjmp
pairs save and restore the signal mask while
.Fn _setjmp Ns / Ns Fn _longjmp
pairs save and restore only the register set and the stack.
(See
.Fn sigprocmask 2 . )
.Pp
The
.Fn sigsetjmp Ns / Ns Fn siglongjmp
function
pairs save and restore the signal mask if the argument
.Fa savemask
is non-zero; otherwise, only the register set and the stack are saved.
.Sh ERRORS
If the contents of the
.Fa env
are corrupted, or correspond to an environment that has already returned,
the
.Fn longjmp
routine calls the routine
.Fn longjmperror 3 .
If
.Fn longjmperror
returns, the program is aborted (see
.Xr abort 3 ) .
The default version of
.Fn longjmperror
prints the message
.Dq Li longjmp botch
to standard error and returns.
User programs wishing to exit more gracefully should write their own
versions of
.Fn longjmperror .
.Sh SEE ALSO
.Xr sigaction 2 ,
.Xr sigaltstack 2 ,
.Xr signal 3
.Sh STANDARDS
The
.Fn setjmp
and
.Fn longjmp
functions conform to
.St -isoC .
The
.Fn sigsetjmp
and
.Fn siglongjmp
functions conform to
.St -p1003.1-88 .
Commit	Line	Data
ada7c492 A	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. All advertising materials mentioning features or use of this software
	17	.\" must display the following acknowledgement:
	18	.\" This product includes software developed by the University of
	19	.\" California, Berkeley and its contributors.
	20	.\" 4. Neither the name of the University nor the names of its contributors
	21	.\" may be used to endorse or promote products derived from this software
	22	.\" without specific prior written permission.
	23	.\"
	24	.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
	25	.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
	26	.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
	27	.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
	28	.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
	29	.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
	30	.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
	31	.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
	32	.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
	33	.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
	34	.\" SUCH DAMAGE.
	35	.\"
	36	.\" @(#)setjmp.3 8.1 (Berkeley) 6/4/93
	37	.\" $FreeBSD: src/lib/libc/gen/setjmp.3,v 1.9 2001/10/01 16:08:51 ru Exp $
	38	.\"
	39	.Dd June 4, 1993
	40	.Dt SETJMP 3
	41	.Os
	42	.Sh NAME
	43	.Nm _longjmp ,
	44	.Nm _setjmp ,
	45	.Nm longjmp ,
	46	.Nm longjmperror ,
	47	.Nm setjmp ,
	48	.Nm siglongjmp ,
	49	.Nm sigsetjmp
	50	.Nd non-local jumps
	51	.Sh LIBRARY
	52	.Lb libc
	53	.Sh SYNOPSIS
	54	.In setjmp.h
	55	.Ft void
	56	.Fo _longjmp
	57	.Fa "jmp_buf env"
	58	.Fa "int val"
	59	.Fc
	60	.Ft int
	61	.Fo _setjmp
	62	.Fa "jmp_buf env"
	63	.Fc
	64	.Ft void
65	.Fo longjmp
66	.Fa "jmp_buf env"
67	.Fa "int val"
68	.Fc
69	.Ft void
70	.Fo longjmperror
71	.Fa void
72	.Fc
73	.Ft int
74	.Fo setjmp
75	.Fa "jmp_buf env"
76	.Fc
77	.Ft void
78	.Fo siglongjmp
79	.Fa "sigjmp_buf env"
80	.Fa "int val"
81	.Fc
82	.Ft int
83	.Fo sigsetjmp
84	.Fa "sigjmp_buf env"
85	.Fa "int savemask"
86	.Fc
87	.Sh DESCRIPTION
88	The
89	.Fn sigsetjmp ,
90	.Fn setjmp ,
91	and
92	.Fn _setjmp
93	functions save their calling environment in
94	.Fa env .
95	Each of these functions returns 0.
96	.Pp
97	The corresponding
98	.Fn longjmp
99	functions restore the environment saved by their most recent respective
100	invocations
101	of the
102	.Fn setjmp
103	function.
104	They then return, so that program execution continues
105	as if the corresponding invocation of the
106	.Fn setjmp
107	call had just returned the value specified by
108	.Fa val ,
109	instead of 0.
110	.Pp
111	Pairs of calls may be intermixed
112	(i.e., both
113	.Fn sigsetjmp
114	and
115	.Fn siglongjmp
116	and
117	.Fn setjmp
118	and
119	.Fn longjmp
120	combinations may be used in the same program); however, individual
121	calls may not (e.g. the
122	.Fa env
123	argument to
124	.Fn setjmp
125	may not be passed to
126	.Fn siglongjmp ) .
127	.Pp
128	The
129	.Fn longjmp
130	routines may not be called after the routine which called the
131	.Fn setjmp
132	routines returns.
133	.Pp
134	All accessible objects have values as of the time
135	.Fn longjmp
136	routine was called, except that the values of objects of automatic storage
137	invocation duration that do not have the
138	.Em volatile
139	type and have been changed between the
140	.Fn setjmp
141	invocation and
142	.Fn longjmp
143	call are indeterminate.
144	.Pp
145	The
146	.Fn setjmp Ns / Ns Fn longjmp
147	pairs save and restore the signal mask while
148	.Fn _setjmp Ns / Ns Fn _longjmp
149	pairs save and restore only the register set and the stack.
150	(See
151	.Fn sigprocmask 2 . )
152	.Pp
153	The
154	.Fn sigsetjmp Ns / Ns Fn siglongjmp
155	function
156	pairs save and restore the signal mask if the argument
157	.Fa savemask
158	is non-zero; otherwise, only the register set and the stack are saved.
159	.Sh ERRORS
160	If the contents of the
161	.Fa env
162	are corrupted, or correspond to an environment that has already returned,
163	the
164	.Fn longjmp
165	routine calls the routine
166	.Fn longjmperror 3 .
167	If
168	.Fn longjmperror
169	returns, the program is aborted (see
170	.Xr abort 3 ) .
171	The default version of
172	.Fn longjmperror
173	prints the message
174	.Dq Li longjmp botch
175	to standard error and returns.
176	User programs wishing to exit more gracefully should write their own
177	versions of
178	.Fn longjmperror .
179	.Sh SEE ALSO
180	.Xr sigaction 2 ,
181	.Xr sigaltstack 2 ,
182	.Xr signal 3
183	.Sh STANDARDS
184	The
185	.Fn setjmp
186	and
187	.Fn longjmp
188	functions conform to
189	.St -isoC .
190	The
191	.Fn sigsetjmp
192	and
193	.Fn siglongjmp
194	functions conform to
195	.St -p1003.1-88 .