Annotation of src/lib/libc/sys/sigaltstack.2, Revision 1.11
1.11 ! jdolecek 1: .\" $NetBSD: sigaltstack.2,v 1.10 1999/05/12 18:42:43 sommerfe Exp $
1.3 cgd 2: .\"
1.1 cgd 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: .\"
1.7 perry 34: .\" @(#)sigaltstack.2 8.2 (Berkeley) 5/1/95
1.1 cgd 35: .\"
1.7 perry 36: .Dd May 1, 1995
1.1 cgd 37: .Dt SIGALTSTACK 2
1.9 garbled 38: .Os
1.1 cgd 39: .Sh NAME
40: .Nm sigaltstack
41: .Nd set and/or get signal stack context
42: .Sh SYNOPSIS
43: .Fd #include <signal.h>
1.5 mikel 44: .Pp
1.1 cgd 45: .Bd -literal
1.7 perry 46: typedef struct sigaltstack {
1.6 kleink 47: void *ss_sp;
48: size_t ss_size;
1.1 cgd 49: int ss_flags;
1.6 kleink 50: } stack_t;
1.1 cgd 51: .Ed
52: .Ft int
1.6 kleink 53: .Fn sigaltstack "const stack_t *ss" "stack_t *oss"
1.1 cgd 54: .Sh DESCRIPTION
1.8 lukem 55: .Fn sigaltstack
1.4 mouse 56: allows users to define an alternative stack on which signals
1.1 cgd 57: are to be processed.
58: If
59: .Fa ss
60: is non-zero,
61: it specifies a pointer to and the size of a
62: .Em "signal stack"
63: on which to deliver signals,
64: and tells the system if the process is currently executing
65: on that stack.
66: When a signal's action indicates its handler
67: should execute on the signal stack (specified with a
68: .Xr sigaction 2
69: call), the system checks to see
70: if the process is currently executing on that stack.
71: If the process is not currently executing on the signal stack,
72: the system arranges a switch to the signal stack for the
73: duration of the signal handler's execution.
74: .Pp
75: If
1.5 mikel 76: .Dv SS_DISABLE
1.1 cgd 77: is set in
78: .Fa ss_flags ,
79: .Fa ss_sp
80: and
81: .Fa ss_size
82: are ignored and the signal stack will be disabled.
83: Trying to disable an active stack will cause
84: .Nm
85: to return -1 with
86: .Va errno
87: set to
88: .Dv EINVAL .
89: A disabled stack will cause all signals to be
90: taken on the regular user stack.
91: If the stack is later re-enabled then all signals that were specified
1.4 mouse 92: to be processed on an alternative stack will resume doing so.
1.1 cgd 93: .Pp
94: If
95: .Fa oss
96: is non-zero, the current signal stack state is returned.
97: The
98: .Fa ss_flags
99: field will contain the value
1.5 mikel 100: .Dv SS_ONSTACK
1.1 cgd 101: if the process is currently on a signal stack and
1.5 mikel 102: .Dv SS_DISABLE
1.1 cgd 103: if the signal stack is currently disabled.
104: .Sh NOTES
105: The value
106: .Dv SIGSTKSZ
107: is defined to be the number of bytes/chars that would be used to cover
1.4 mouse 108: the usual case when allocating an alternative stack area.
109: The following code fragment is typically used to allocate an alternative stack.
1.1 cgd 110: .Bd -literal -offset indent
111: if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL)
112: /* error return */
113: sigstk.ss_size = SIGSTKSZ;
114: sigstk.ss_flags = 0;
115: if (sigaltstack(&sigstk,0) < 0)
116: perror("sigaltstack");
117: .Ed
1.5 mikel 118: .Pp
1.1 cgd 119: An alternative approach is provided for programs with signal handlers
120: that require a specific amount of stack space other than the default size.
121: The value
122: .Dv MINSIGSTKSZ
123: is defined to be the number of bytes/chars that is required by
1.4 mouse 124: the operating system to implement the alternative stack feature.
125: In computing an alternative stack size,
1.1 cgd 126: programs should add
127: .Dv MINSIGSTKSZ
128: to their stack requirements to allow for the operating system overhead.
129: .Pp
130: Signal stacks are automatically adjusted for the direction of stack
131: growth and alignment requirements.
132: Signal stacks may or may not be protected by the hardware and
133: are not ``grown'' automatically as is done for the normal stack.
134: If the stack overflows and this space is not protected
135: unpredictable results may occur.
136: .Sh RETURN VALUES
137: Upon successful completion, a value of 0 is returned.
138: Otherwise, a value of -1 is returned and
139: .Va errno
140: is set to indicate the error.
141: .Sh ERRORS
1.10 sommerfe 142: .Fn sigaltstack
1.1 cgd 143: will fail and the signal stack context will remain unchanged
144: if one of the following occurs.
1.5 mikel 145: .Bl -tag -width Er
1.1 cgd 146: .It Bq Er EFAULT
147: Either
148: .Fa ss
149: or
150: .Fa oss
151: points to memory that is not a valid part of the process
152: address space.
153: .It Bq Er EINVAL
154: An attempt was made to disable an active stack.
155: .It Bq Er ENOMEM
1.4 mouse 156: Size of alternative stack area is less than or equal to
1.1 cgd 157: .Dv MINSIGSTKSZ .
158: .El
159: .Sh SEE ALSO
160: .Xr sigaction 2 ,
1.11 ! jdolecek 161: .Xr setjmp 3 ,
! 162: .Xr signal 7
1.6 kleink 163: .Sh STANDARDS
164: The
165: .Fn sigaltstack
166: function conforms to
167: .St -xpg4.2 .
1.1 cgd 168: .Sh HISTORY
169: The predecessor to
170: .Nm sigaltstack ,
171: the
172: .Fn sigstack
173: system call, appeared in
174: .Bx 4.2 .
CVSweb <webmaster@jp.NetBSD.org>
![[BACK]](/icons/back.gif){kind=icon}
Return to sigaltstack.2 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [cvs.NetBSD.org] / src / lib / libc / sys