[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 _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
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
5b2abdfb	43	.Nm _longjmp ,
224c7076 A	44	.Nm _setjmp ,
	45	.Nm longjmp ,
	46	.Nm longjmperror ,
	47	.Nm setjmp ,
	48	.Nm siglongjmp ,
	49	.Nm sigsetjmp
5b2abdfb A	50	.Nd non-local jumps
	51	.Sh LIBRARY
	52	.Lb libc
	53	.Sh SYNOPSIS
	54	.In setjmp.h
5b2abdfb	55	.Ft void
224c7076 A	56	.Fo _longjmp
	57	.Fa "jmp_buf env"
	58	.Fa "int val"
	59	.Fc
5b2abdfb	60	.Ft int
224c7076 A	61	.Fo _setjmp
	62	.Fa "jmp_buf env"
	63	.Fc
5b2abdfb	64	.Ft void
224c7076 A	65	.Fo longjmp
	66	.Fa "jmp_buf env"
	67	.Fa "int val"
	68	.Fc
5b2abdfb	69	.Ft void
224c7076 A	70	.Fo longjmperror
	71	.Fa void
	72	.Fc
	73	.Ft int
	74	.Fo setjmp
	75	.Fa "jmp_buf env"
	76	.Fc
5b2abdfb	77	.Ft void
224c7076 A	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
5b2abdfb A	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.
224c7076 A	104	They then return, so that program execution continues
224c7076 A	105	as if the corresponding invocation of the
5b2abdfb	106	.Fn setjmp
224c7076	107	call had just returned the value specified by
5b2abdfb A	108	.Fa val ,
	109	instead of 0.
	110	.Pp
224c7076 A	111	Pairs of calls may be intermixed
224c7076 A	112	(i.e., both
5b2abdfb A	113	.Fn sigsetjmp
	114	and
	115	.Fn siglongjmp
	116	and
	117	.Fn setjmp
	118	and
	119	.Fn longjmp
224c7076 A	120	combinations may be used in the same program); however, individual
224c7076 A	121	calls may not (e.g. the
5b2abdfb A	122	.Fa env
	123	argument to
	124	.Fn setjmp
	125	may not be passed to
224c7076	126	.Fn siglongjmp ) .
5b2abdfb A	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
224c7076	158	is non-zero; otherwise, only the register set and the stack are saved.
5b2abdfb A	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
224c7076	169	returns, the program is aborted (see
5b2abdfb A	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 .