8322 nl: misleading-indentation
[unleashed/tickless.git] / usr / src / man / man2 / sigaction.2
blob36c4ef1a9a543285b8442d1c5c7cb67dab4214e6
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc.  All Rights Reserved.
3 .\" Copyright 1989 AT&T
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH SIGACTION 2 "Mar 23, 2005"
8 .SH NAME
9 sigaction \- detailed signal management
10 .SH SYNOPSIS
11 .LP
12 .nf
13 #include <signal.h>
15 \fBint\fR \fBsigaction\fR(\fBint\fR \fIsig\fR, \fBconst struct sigaction *restrict\fR \fIact\fR,
16      \fBstruct sigaction *restrict\fR \fIoact\fR);
17 .fi
19 .SH DESCRIPTION
20 .sp
21 .LP
22 The \fBsigaction()\fR function allows the calling process to examine or specify
23 the action to be taken on delivery of a specific signal. See
24 \fBsignal.h\fR(3HEAD) for an explanation of general signal concepts.
25 .sp
26 .LP
27 The \fIsig\fR argument specifies the signal and can be assigned any of the
28 signals specified in \fBsignal.h\fR(3HEAD) except  \fBSIGKILL\fR and
29 \fBSIGSTOP\fR.
30 .sp
31 .LP
32 If the argument \fIact\fR is not \fINULL\fR, it points to a structure
33 specifying the new action to be taken when delivering \fIsig\fR. If the
34 argument \fIoact\fR is not \fINULL\fR, it points to a structure where the
35 action previously associated with \fIsig\fR is to be stored on return from
36 \fBsigaction()\fR.
37 .sp
38 .LP
39 The \fBsigaction\fR structure includes the following members:
40 .sp
41 .in +2
42 .nf
43 void      (*sa_handler)(\|);
44 void      (*sa_sigaction)(int, siginfo_t *, void *);
45 sigset_t  sa_mask;
46 int       sa_flags;
47 .fi
48 .in -2
50 .sp
51 .LP
52 The storage occupied by \fBsa_handler\fR and \fBsa_sigaction\fR may overlap,
53 and a standard-conforming application (see \fBstandards\fR(5)) must not use
54 both simultaneously.
55 .sp
56 .LP
57 The \fBsa_handler\fR member identifies the action to be associated with the
58 specified signal, if the  \fBSA_SIGINFO\fR flag (see below) is cleared in the
59 \fBsa_flags\fR field of the sigaction structure. It may take any of the values
60 specified in \fBsignal.h\fR(3HEAD) or that of a user specified signal handler.
61 If the  \fBSA_SIGINFO\fR flag is set in the \fBsa_flags\fR field, the
62 \fBsa_sigaction\fR field specifies a signal-catching function.
63 .sp
64 .LP
65 The \fBsa_mask\fR member specifies a set of signals to be blocked while the
66 signal handler is active. On entry to the signal handler, that set of signals
67 is added to the set of signals already being blocked when the signal is
68 delivered. In addition, the signal that caused the handler to be executed will
69 also be blocked, unless the  \fBSA_NODEFER\fR flag has been specified.
70 \fBSIGSTOP\fR and  \fBSIGKILL\fR cannot be blocked (the system silently
71 enforces this restriction).
72 .sp
73 .LP
74 The \fBsa_flags\fR member specifies a set of flags used to modify the delivery
75 of the signal. It is formed by a logical \fBOR\fR of any of the following
76 values:
77 .sp
78 .ne 2
79 .na
80 \fB\fBSA_ONSTACK\fR\fR
81 .ad
82 .RS 16n
83 If set and the signal is caught, and if the thread that is chosen to processes
84 a delivered signal has an alternate signal stack declared with
85 \fBsigaltstack\fR(2), then it will process the signal on that stack. Otherwise,
86 the signal is delivered on the thread's normal stack.
87 .RE
89 .sp
90 .ne 2
91 .na
92 \fB\fBSA_RESETHAND\fR\fR
93 .ad
94 .RS 16n
95 If set and the signal is caught, the disposition of the signal is reset to
96 \fBSIG_DFL\fR and the signal will not be blocked on entry to the signal handler
97 (\fBSIGILL\fR, \fBSIGTRAP\fR, and \fBSIGPWR\fR cannot be  automatically reset
98 when delivered; the system silently enforces this restriction).
99 .RE
102 .ne 2
104 \fB\fBSA_NODEFER\fR\fR
106 .RS 16n
107 If set and the signal is caught, the signal will not be automatically blocked
108 by the kernel while it is being caught.
112 .ne 2
114 \fB\fBSA_RESTART\fR\fR
116 .RS 16n
117 If set and the signal is caught, functions that are interrupted by the
118 execution of this signal's handler are transparently restarted by the system,
119 namely \fBfcntl\fR(2), \fBioctl\fR(2), \fBwait\fR(3C), \fBwaitid\fR(2), and the
120 following functions on slow devices like terminals: \fBgetmsg()\fR and
121 \fBgetpmsg()\fR (see \fBgetmsg\fR(2));  \fBputmsg()\fR and \fBputpmsg()\fR (see
122 \fBputmsg\fR(2)); \fBpread()\fR, \fBread()\fR, and \fBreadv()\fR (see
123 \fBread\fR(2)); \fBpwrite()\fR, \fBwrite()\fR, and \fBwritev()\fR (see
124 \fBwrite\fR(2)); \fBrecv()\fR, \fBrecvfrom()\fR, and \fBrecvmsg()\fR (see
125 \fBrecv\fR(3SOCKET)); and \fBsend()\fR, \fBsendto()\fR, and \fBsendmsg()\fR
126 (see \fBsend\fR(3SOCKET)). Otherwise, the function returns an \fBEINTR\fR
127 error.
131 .ne 2
133 \fB\fBSA_SIGINFO\fR\fR
135 .RS 16n
136 If cleared and the signal is caught, \fIsig\fR is passed as the only argument
137 to the signal-catching function. If set and the signal is caught,  two
138 additional arguments are passed to the signal-catching function.  If the second
139 argument is not equal to \fINULL\fR, it points to a \fBsiginfo_t\fR structure
140 containing the reason why the signal was generated (see
141 \fBsiginfo.h\fR(3HEAD)); the third argument points to a \fBucontext_t\fR
142 structure containing the receiving process's context when the signal was
143 delivered (see \fBucontext.h\fR(3HEAD)).
147 .ne 2
149 \fB\fBSA_NOCLDWAIT\fR\fR
151 .RS 16n
152 If set and \fIsig\fR equals  \fBSIGCHLD\fR, the system will not create zombie
153 processes when children of the calling process exit. If the calling process
154 subsequently issues a \fBwait\fR(3C), it blocks until all of the calling
155 process's child processes terminate, and then returns \fB\(mi1\fR with
156 \fBerrno\fR set to \fBECHILD\fR.
160 .ne 2
162 \fB\fBSA_NOCLDSTOP\fR\fR
164 .RS 16n
165 If set and \fIsig\fR equals \fBSIGCHLD\fR, \fBSIGCHLD\fR will not be sent to
166 the calling process when its child processes stop or continue.
169 .SH RETURN VALUES
172 Upon successful completion, \fB0\fR is returned. Otherwise, \fB\(mi1\fR is
173 returned, \fBerrno\fR is set to indicate the error, and no new signal handler
174 is installed.
175 .SH ERRORS
178 The \fBsigaction()\fR function will fail if:
180 .ne 2
182 \fB\fBEINVAL\fR\fR
184 .RS 10n
185 The value of the \fIsig\fR argument is not a valid signal number or is equal to
186 \fBSIGKILL\fR or \fBSIGSTOP\fR. In addition, if in a multithreaded process, it
187 is equal to \fBSIGWAITING\fR, \fBSIGCANCEL\fR, or \fBSIGLWP\fR.
190 .SH ATTRIBUTES
193 See \fBattributes\fR(5) for descriptions of the following attributes:
198 box;
199 c | c
200 l | l .
201 ATTRIBUTE TYPE  ATTRIBUTE VALUE
203 Interface Stability     Committed
205 MT-Level        Async-Signal-Safe
207 Standard        See \fBstandards\fR(5).
210 .SH SEE ALSO
213 \fBkill\fR(1), \fBIntro\fR(2), \fBexit\fR(2), \fBfcntl\fR(2), \fBgetmsg\fR(2),
214 \fBioctl\fR(2), \fBkill\fR(2), \fBpause\fR(2), \fBputmsg\fR(2), \fBread\fR(2),
215 \fBsigaltstack\fR(2), \fBsigprocmask\fR(2), \fBsigsend\fR(2),
216 \fBsigsuspend\fR(2), \fBwaitid\fR(2), \fBwrite\fR(2), \fBrecv\fR(3SOCKET),
217 \fBsend\fR(3SOCKET), \fBsiginfo.h\fR(3HEAD), \fBsignal\fR(3C),
218 \fBsignal.h\fR(3HEAD), \fBsigsetops\fR(3C), \fBucontext.h\fR(3HEAD),
219 \fBwait\fR(3C), \fBattributes\fR(5), \fBstandards\fR(5)
220 .SH NOTES
223 The handler routine can be declared:
225 .in +2
227 void handler (int \fIsig\fR, siginfo_t *\fIsip\fR, ucontext_t *\fIucp\fR);
229 .in -2
233 The \fIsig\fR argument is the signal number. The \fIsip\fR argument is a
234 pointer (to space on the stack) to a \fBsiginfo_t\fR structure, which provides
235 additional detail about the delivery of the signal. The \fIucp\fR argument is a
236 pointer (again to space on the stack) to a \fBucontext_t\fR structure (defined
237 in <\fBsys/ucontext.h\fR>) which contains the context from before the signal.
238 It is not recommended that \fIucp\fR be used by the handler to restore the
239 context from before the signal delivery.