[apple/xnu.git] / bsd / man / man2 / sigaltstack.2

.\"	$NetBSD: sigaltstack.2,v 1.3 1995/02/27 10:41:52 cgd Exp $
.\"
.\" Copyright (c) 1983, 1991, 1992, 1993
.\"	The Regents of the University of California.  All rights reserved.
.\"
.\" 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.
.\"
.\"     @(#)sigaltstack.2	8.1 (Berkeley) 6/4/93
.\"
.Dd June 4, 1993
.Dt SIGALTSTACK 2
.Os BSD 4.2
.Sh NAME
.Nm sigaltstack
.Nd set and/or get signal stack context
.Sh SYNOPSIS
.Fd #include <signal.h>
.Ft int
.Fo sigaltstack
.Fa "const stack_t *restrict ss"
.Fa "stack_t *restrict oss"
.Fc
.Sh DESCRIPTION
.Fn Sigaltstack
allows users to define an alternate stack on which signals
are to be processed.
If
.Fa ss
is non-zero,
it specifies a pointer to and the size of a
.Em "signal stack"
on which to deliver signals,
and tells the system if the process is currently executing
on that stack.
When a signal's action indicates its handler
should execute on the signal stack (specified with a
.Xr sigaction 2
call), the system checks to see
if the process is currently executing on that stack.
If the process is not currently executing on the signal stack,
the system arranges a switch to the signal stack for the
duration of the signal handler's execution. 
.Pp
If
.Dv SS_DISABLE
is set in
.Fa ss_flags ,
.Fa ss_sp
and
.Fa ss_size
are ignored and the signal stack will be disabled.
Trying to disable an active stack will cause
.Nm
to return -1 with
.Va errno
set to
.Dv EINVAL .
A disabled stack will cause all signals to be
taken on the regular user stack.
If the stack is later re-enabled then all signals that were specified
to be processed on an alternate stack will resume doing so.
.Pp
If
.Fa oss
is non-zero, the current signal stack state is returned.
The
.Fa ss_flags
field will contain the value
.Dv SA_ONSTACK
if the process is currently on a signal stack and
.Dv SS_DISABLE
if the signal stack is currently disabled.
.Sh NOTES
The value
.Dv SIGSTKSZ
is defined to be the number of bytes/chars that would be used to cover
the usual case when allocating an alternate stack area.
The following code fragment is typically used to allocate an alternate stack.
.Bd -literal -offset indent
if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL)
	/* error return */
sigstk.ss_size = SIGSTKSZ;
sigstk.ss_flags = 0;
if (sigaltstack(&sigstk,0) < 0)
	perror("sigaltstack");
.Ed
An alternative approach is provided for programs with signal handlers
that require a specific amount of stack space other than the default size.
The value
.Dv MINSIGSTKSZ
is defined to be the number of bytes/chars that is required by
the operating system to implement the alternate stack feature.
In computing an alternate stack size,
programs should add
.Dv MINSIGSTKSZ
to their stack requirements to allow for the operating system overhead.
.Pp
Signal stacks are automatically adjusted for the direction of stack
growth and alignment requirements.
Signal stacks may or may not be protected by the hardware and
are not ``grown'' automatically as is done for the normal stack.
If the stack overflows and this space is not protected
unpredictable results may occur.
.Sh RETURN VALUES
Upon successful completion, a value of 0 is returned.
Otherwise, a value of -1 is returned and 
.Va errno
is set to indicate the error.
.Sh ERRORS
.Fn Sigaltstack
will fail and the signal stack context will remain unchanged
if one of the following occurs.
.Bl -tag -width [ENOMEM]
.\" ===========
.It Bq Er EFAULT
Either
.Fa ss
or
.Fa oss
points to memory that is not a valid part of the process
address space.
.\" ===========
.It Bq Er EINVAL
An attempt is made to disable an active stack.
.\" ===========
.It Bq Er EINVAL
The
.Fa ss
argument is not a null pointer, and the ss_flags member
pointed to by
.Fa ss
contains flags other than SS_DISABLE.
.\" ===========
.It Bq Er ENOMEM
The size of the alternate stack area is less than or equal to
.Dv MINSIGSTKSZ .
.\" ===========
.It Bq Er EPERM
An attempt was made to modify an active stack.
.El
.Sh LEGACY SYNOPSIS
.Fd #include <sys/types.h>
.Fd #include <signal.h>
.Pp
The include file
.In sys/types.h
is necessary.
.Pp
.Bd -literal
struct sigaltstack {
	char   *ss_sp;
	int	ss_size;
	int     ss_flags;
};
.Ed
.Pp
.Ft int
.br
.Fo sigaltstack
.Fa "const struct sigaltstack *ss"
.Fa "struct sigaltstack *oss"
.Fc ;
.Pp
The variable types have changed.
Specifically, the
.Vt sigaltstack
struct is no longer used.
.Sh COMPATIBILITY
Use of the (obsolete)
.Vt sigaltstack
struct will cause compiler diagnostics.
Use
.Vt stack_t ,
defined in
.In signal.h .
.Sh SEE ALSO
.Xr sigaction 2 ,
.Xr setjmp 3 ,
.Xr compat 5
.Sh HISTORY
The predecessor to
.Nm sigaltstack ,
the
.Fn sigstack
system call, appeared in
.Bx 4.2 .
Commit	Line	Data
9bccf70c A	1	.\" $NetBSD: sigaltstack.2,v 1.3 1995/02/27 10:41:52 cgd Exp $
	2	.\"
	3	.\" Copyright (c) 1983, 1991, 1992, 1993
	4	.\" The Regents of the University of California. All rights reserved.
	5	.\"
	6	.\" Redistribution and use in source and binary forms, with or without
	7	.\" modification, are permitted provided that the following conditions
	8	.\" are met:
	9	.\" 1. Redistributions of source code must retain the above copyright
	10	.\" notice, this list of conditions and the following disclaimer.
	11	.\" 2. Redistributions in binary form must reproduce the above copyright
	12	.\" notice, this list of conditions and the following disclaimer in the
	13	.\" documentation and/or other materials provided with the distribution.
	14	.\" 3. All advertising materials mentioning features or use of this software
	15	.\" must display the following acknowledgement:
	16	.\" This product includes software developed by the University of
	17	.\" California, Berkeley and its contributors.
	18	.\" 4. 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	.\" @(#)sigaltstack.2 8.1 (Berkeley) 6/4/93
	35	.\"
	36	.Dd June 4, 1993
	37	.Dt SIGALTSTACK 2
	38	.Os BSD 4.2
	39	.Sh NAME
	40	.Nm sigaltstack
	41	.Nd set and/or get signal stack context
	42	.Sh SYNOPSIS
9bccf70c	43	.Fd #include <signal.h>
9bccf70c	44	.Ft int
2d21ac55 A	45	.Fo sigaltstack
	46	.Fa "const stack_t *restrict ss"
	47	.Fa "stack_t *restrict oss"
	48	.Fc
9bccf70c A	49	.Sh DESCRIPTION
	50	.Fn Sigaltstack
	51	allows users to define an alternate stack on which signals
	52	are to be processed.
	53	If
	54	.Fa ss
	55	is non-zero,
	56	it specifies a pointer to and the size of a
	57	.Em "signal stack"
	58	on which to deliver signals,
	59	and tells the system if the process is currently executing
	60	on that stack.
	61	When a signal's action indicates its handler
	62	should execute on the signal stack (specified with a
	63	.Xr sigaction 2
	64	call), the system checks to see
	65	if the process is currently executing on that stack.
	66	If the process is not currently executing on the signal stack,
	67	the system arranges a switch to the signal stack for the
	68	duration of the signal handler's execution.
	69	.Pp
	70	If
39236c6e	71	.Dv SS_DISABLE
9bccf70c A	72	is set in
	73	.Fa ss_flags ,
	74	.Fa ss_sp
	75	and
	76	.Fa ss_size
	77	are ignored and the signal stack will be disabled.
	78	Trying to disable an active stack will cause
	79	.Nm
	80	to return -1 with
	81	.Va errno
	82	set to
	83	.Dv EINVAL .
	84	A disabled stack will cause all signals to be
	85	taken on the regular user stack.
	86	If the stack is later re-enabled then all signals that were specified
	87	to be processed on an alternate stack will resume doing so.
	88	.Pp
	89	If
	90	.Fa oss
	91	is non-zero, the current signal stack state is returned.
	92	The
	93	.Fa ss_flags
	94	field will contain the value
	95	.Dv SA_ONSTACK
	96	if the process is currently on a signal stack and
39236c6e	97	.Dv SS_DISABLE
9bccf70c A	98	if the signal stack is currently disabled.
	99	.Sh NOTES
	100	The value
	101	.Dv SIGSTKSZ
	102	is defined to be the number of bytes/chars that would be used to cover
	103	the usual case when allocating an alternate stack area.
	104	The following code fragment is typically used to allocate an alternate stack.
	105	.Bd -literal -offset indent
	106	if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL)
	107	/* error return */
	108	sigstk.ss_size = SIGSTKSZ;
	109	sigstk.ss_flags = 0;
	110	if (sigaltstack(&sigstk,0) < 0)
	111	perror("sigaltstack");
	112	.Ed
	113	An alternative approach is provided for programs with signal handlers
	114	that require a specific amount of stack space other than the default size.
	115	The value
	116	.Dv MINSIGSTKSZ
	117	is defined to be the number of bytes/chars that is required by
	118	the operating system to implement the alternate stack feature.
	119	In computing an alternate stack size,
	120	programs should add
	121	.Dv MINSIGSTKSZ
	122	to their stack requirements to allow for the operating system overhead.
	123	.Pp
	124	Signal stacks are automatically adjusted for the direction of stack
	125	growth and alignment requirements.
	126	Signal stacks may or may not be protected by the hardware and
	127	are not ``grown'' automatically as is done for the normal stack.
	128	If the stack overflows and this space is not protected
	129	unpredictable results may occur.
	130	.Sh RETURN VALUES
	131	Upon successful completion, a value of 0 is returned.
	132	Otherwise, a value of -1 is returned and
	133	.Va errno
	134	is set to indicate the error.
	135	.Sh ERRORS
2d21ac55	136	.Fn Sigaltstack
9bccf70c A	137	will fail and the signal stack context will remain unchanged
	138	if one of the following occurs.
	139	.Bl -tag -width [ENOMEM]
2d21ac55	140	.\" ===========
9bccf70c A	141	.It Bq Er EFAULT
	142	Either
	143	.Fa ss
	144	or
	145	.Fa oss
	146	points to memory that is not a valid part of the process
	147	address space.
2d21ac55	148	.\" ===========
9bccf70c	149	.It Bq Er EINVAL
2d21ac55 A	150	An attempt is made to disable an active stack.
	151	.\" ===========
	152	.It Bq Er EINVAL
	153	The
	154	.Fa ss
	155	argument is not a null pointer, and the ss_flags member
	156	pointed to by
	157	.Fa ss
	158	contains flags other than SS_DISABLE.
	159	.\" ===========
9bccf70c	160	.It Bq Er ENOMEM
2d21ac55	161	The size of the alternate stack area is less than or equal to
9bccf70c	162	.Dv MINSIGSTKSZ .
2d21ac55 A	163	.\" ===========
	164	.It Bq Er EPERM
	165	An attempt was made to modify an active stack.
9bccf70c	166	.El
2d21ac55 A	167	.Sh LEGACY SYNOPSIS
	168	.Fd #include <sys/types.h>
	169	.Fd #include <signal.h>
	170	.Pp
	171	The include file
	172	.In sys/types.h
	173	is necessary.
	174	.Pp
	175	.Bd -literal
	176	struct sigaltstack {
	177	char *ss_sp;
	178	int ss_size;
	179	int ss_flags;
	180	};
	181	.Ed
	182	.Pp
	183	.Ft int
	184	.br
	185	.Fo sigaltstack
	186	.Fa "const struct sigaltstack *ss"
	187	.Fa "struct sigaltstack *oss"
	188	.Fc ;
	189	.Pp
	190	The variable types have changed.
	191	Specifically, the
	192	.Vt sigaltstack
	193	struct is no longer used.
	194	.Sh COMPATIBILITY
	195	Use of the (obsolete)
	196	.Vt sigaltstack
	197	struct will cause compiler diagnostics.
	198	Use
	199	.Vt stack_t ,
	200	defined in
	201	.In signal.h .
9bccf70c A	202	.Sh SEE ALSO
9bccf70c A	203	.Xr sigaction 2 ,
2d21ac55 A	204	.Xr setjmp 3 ,
2d21ac55 A	205	.Xr compat 5
9bccf70c A	206	.Sh HISTORY
	207	The predecessor to
	208	.Nm sigaltstack ,
	209	the
	210	.Fn sigstack
	211	system call, appeared in
	212	.Bx 4.2 .