[apple/libc.git] / gen / 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 sigsetjmp ,
.Nm siglongjmp ,
.Nm setjmp ,
.Nm longjmp ,
.Nm _setjmp ,
.Nm _longjmp ,
.Nm longjmperror
.Nd non-local jumps
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In setjmp.h
.Ft int
.Fn sigsetjmp "sigjmp_buf env" "int savemask"
.Ft void
.Fn siglongjmp "sigjmp_buf env" "int val"
.Ft int
.Fn setjmp "jmp_buf env"
.Ft void
.Fn longjmp "jmp_buf env" "int val"
.Ft int
.Fn _setjmp "jmp_buf env"
.Ft void
.Fn _longjmp "jmp_buf env" "int val"
.Ft void
.Fn longjmperror void
.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
5b2abdfb 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 sigsetjmp ,
	44	.Nm siglongjmp ,
	45	.Nm setjmp ,
	46	.Nm longjmp ,
	47	.Nm _setjmp ,
	48	.Nm _longjmp ,
	49	.Nm longjmperror
	50	.Nd non-local jumps
	51	.Sh LIBRARY
	52	.Lb libc
	53	.Sh SYNOPSIS
	54	.In setjmp.h
	55	.Ft int
	56	.Fn sigsetjmp "sigjmp_buf env" "int savemask"
	57	.Ft void
	58	.Fn siglongjmp "sigjmp_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 int
	64	.Fn _setjmp "jmp_buf env"
65	.Ft void
66	.Fn _longjmp "jmp_buf env" "int val"
67	.Ft void
68	.Fn longjmperror void
69	.Sh DESCRIPTION
70	The
71	.Fn sigsetjmp ,
72	.Fn setjmp ,
73	and
74	.Fn _setjmp
75	functions save their calling environment in
76	.Fa env .
77	Each of these functions returns 0.
78	.Pp
79	The corresponding
80	.Fn longjmp
81	functions restore the environment saved by their most recent respective
82	invocations
83	of the
84	.Fn setjmp
85	function.
86	They then return so that program execution continues as if the corresponding
87	invocation of the
88	.Fn setjmp
89	call had just returned the value specified by
90	.Fa val ,
91	instead of 0.
92	.Pp
93	Pairs of calls may be intermixed, i.e. both
94	.Fn sigsetjmp
95	and
96	.Fn siglongjmp
97	and
98	.Fn setjmp
99	and
100	.Fn longjmp
101	combinations may be used in the same program, however, individual
102	calls may not, e.g. the
103	.Fa env
104	argument to
105	.Fn setjmp
106	may not be passed to
107	.Fn siglongjmp .
108	.Pp
109	The
110	.Fn longjmp
111	routines may not be called after the routine which called the
112	.Fn setjmp
113	routines returns.
114	.Pp
115	All accessible objects have values as of the time
116	.Fn longjmp
117	routine was called, except that the values of objects of automatic storage
118	invocation duration that do not have the
119	.Em volatile
120	type and have been changed between the
121	.Fn setjmp
122	invocation and
123	.Fn longjmp
124	call are indeterminate.
125	.Pp
126	The
127	.Fn setjmp Ns / Ns Fn longjmp
128	pairs save and restore the signal mask while
129	.Fn _setjmp Ns / Ns Fn _longjmp
130	pairs save and restore only the register set and the stack.
131	(See
132	.Fn sigprocmask 2 . )
133	.Pp
134	The
135	.Fn sigsetjmp Ns / Ns Fn siglongjmp
136	function
137	pairs save and restore the signal mask if the argument
138	.Fa savemask
139	is non-zero, otherwise only the register set and the stack are saved.
140	.Sh ERRORS
141	If the contents of the
142	.Fa env
143	are corrupted, or correspond to an environment that has already returned,
144	the
145	.Fn longjmp
146	routine calls the routine
147	.Fn longjmperror 3 .
148	If
149	.Fn longjmperror
150	returns the program is aborted (see
151	.Xr abort 3 ) .
152	The default version of
153	.Fn longjmperror
154	prints the message
155	.Dq Li longjmp botch
156	to standard error and returns.
157	User programs wishing to exit more gracefully should write their own
158	versions of
159	.Fn longjmperror .
160	.Sh SEE ALSO
161	.Xr sigaction 2 ,
162	.Xr sigaltstack 2 ,
163	.Xr signal 3
164	.Sh STANDARDS
165	The
166	.Fn setjmp
167	and
168	.Fn longjmp
169	functions conform to
170	.St -isoC .
171	The
172	.Fn sigsetjmp
173	and
174	.Fn siglongjmp
175	functions conform to
176	.St -p1003.1-88 .