Commit | Line | Data |
---|---|---|
15637ed4 RG |
1 | .\" Copyright (c) 1980, 1990 The Regents of the University of California. |
2 | .\" All rights reserved. | |
3 | .\" | |
4 | .\" Redistribution and use in source and binary forms, with or without | |
5 | .\" modification, are permitted provided that the following conditions | |
6 | .\" are met: | |
7 | .\" 1. Redistributions of source code must retain the above copyright | |
8 | .\" notice, this list of conditions and the following disclaimer. | |
9 | .\" 2. Redistributions in binary form must reproduce the above copyright | |
10 | .\" notice, this list of conditions and the following disclaimer in the | |
11 | .\" documentation and/or other materials provided with the distribution. | |
12 | .\" 3. All advertising materials mentioning features or use of this software | |
13 | .\" must display the following acknowledgement: | |
14 | .\" This product includes software developed by the University of | |
15 | .\" California, Berkeley and its contributors. | |
16 | .\" 4. Neither the name of the University nor the names of its contributors | |
17 | .\" may be used to endorse or promote products derived from this software | |
18 | .\" without specific prior written permission. | |
19 | .\" | |
20 | .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND | |
21 | .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE | |
22 | .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE | |
23 | .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE | |
24 | .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL | |
25 | .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS | |
26 | .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) | |
27 | .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT | |
28 | .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY | |
29 | .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF | |
30 | .\" SUCH DAMAGE. | |
31 | .\" | |
32 | .\" @(#)sigaction.2 6.3 (Berkeley) 7/23/91 | |
33 | .\" | |
34 | .Dd July 23, 1991 | |
35 | .Dt SIGACTION 2 | |
36 | .Os | |
37 | .Sh NAME | |
38 | .Nm sigaction | |
39 | .Nd software signal facilities | |
40 | .Sh SYNOPSIS | |
41 | .Fd #include <signal.h> | |
42 | .Bd -literal | |
43 | struct sigaction { | |
44 | void (*sa_handler)(); | |
45 | sigset_t sa_mask; | |
46 | int sa_flags; | |
47 | }; | |
48 | .Ed | |
49 | .Fn sigaction "int sig" "struct sigaction *act" "struct sigaction *oact" | |
50 | .Sh DESCRIPTION | |
51 | The system defines a set of signals that may be delivered to a process. | |
52 | Signal delivery resembles the occurence of a hardware interrupt: | |
53 | the signal is blocked from further occurrence, the current process | |
54 | context is saved, and a new one is built. A process may specify a | |
55 | .Em handler | |
56 | to which a signal is delivered, or specify that a signal is to be | |
57 | .Em ignored . | |
58 | A process may also specify that a default action is to be taken | |
59 | by the system when a signal occurs. | |
60 | A signal may also be | |
61 | .Em blocked , | |
62 | in which case its delivery is postponed until it is | |
63 | .Em unblocked . | |
64 | The action to be taken on delivery is determined at the time | |
65 | of delivery. | |
66 | Normally, signal handlers execute on the current stack | |
67 | of the process. This may be changed, on a per-handler basis, | |
68 | so that signals are taken on a special | |
69 | .Em "signal stack" . | |
70 | .Pp | |
71 | Signal routines execute with the signal that caused their | |
72 | invocation | |
73 | .Em blocked , | |
74 | but other signals may yet occur. | |
75 | A global | |
76 | .Em "signal mask" | |
77 | defines the set of signals currently blocked from delivery | |
78 | to a process. The signal mask for a process is initialized | |
79 | from that of its parent (normally empty). It | |
80 | may be changed with a | |
81 | .Xr sigprocmask 2 | |
82 | call, or when a signal is delivered to the process. | |
83 | .Pp | |
84 | When a signal | |
85 | condition arises for a process, the signal is added to a set of | |
86 | signals pending for the process. | |
87 | If the signal is not currently | |
88 | .Em blocked | |
89 | by the process then it is delivered to the process. | |
90 | Signals may be delivered any time a process enters the operating system | |
91 | (e.g., during a system call, page fault or trap, or clock interrupt). | |
92 | If multiple signals are ready to be delivered at the same time, | |
93 | any signals that could be caused by traps are delivered first. | |
94 | Additional signals may be processed at the same time, with each | |
95 | appearing to interrupt the handlers for the previous signals | |
96 | before their first instructions. | |
97 | The set of pending signals is returned by the | |
98 | .Xr sigpending 2 | |
99 | function. | |
100 | When a caught signal | |
101 | is delivered, the current state of the process is saved, | |
102 | a new signal mask is calculated (as described below), | |
103 | and the signal handler is invoked. The call to the handler | |
104 | is arranged so that if the signal handling routine returns | |
105 | normally the process will resume execution in the context | |
106 | from before the signal's delivery. | |
107 | If the process wishes to resume in a different context, then it | |
108 | must arrange to restore the previous context itself. | |
109 | .Pp | |
110 | When a signal is delivered to a process a new signal mask is | |
111 | installed for the duration of the process' signal handler | |
112 | (or until a | |
113 | .Xr sigprocmask | |
114 | call is made). | |
115 | This mask is formed by taking the union of the current signal mask set, | |
116 | the signal to be delivered, and | |
117 | the signal mask associated with the handler to be invoked. | |
118 | .Pp | |
119 | .Fn Sigaction | |
120 | assigns an action for a specific signal. | |
121 | If | |
122 | .Fa act | |
123 | is non-zero, it | |
124 | specifies an action | |
125 | .Pf ( Dv SIG_DFL , | |
126 | .Dv SIG_IGN , | |
127 | or a handler routine) and mask | |
128 | to be used when delivering the specified signal. | |
129 | If | |
130 | .Fa oact | |
131 | is non-zero, the previous handling information for the signal | |
132 | is returned to the user. | |
133 | .Pp | |
134 | Once a signal handler is installed, it remains installed | |
135 | until another | |
136 | .Fn sigaction | |
137 | call is made, or an | |
138 | .Xr execve 2 | |
139 | is performed. | |
140 | A signal-specific default action may be reset by | |
141 | setting | |
142 | .Fa sa_handler | |
143 | to | |
144 | .Dv SIG_DFL . | |
145 | The defaults are process termination, possibly with core dump; | |
146 | no action; stopping the process; or continuing the process. | |
147 | See the signal list below for each signal's default action. | |
148 | If | |
149 | .Fa sa_handler | |
150 | is | |
151 | .Dv SIG_IGN | |
152 | current and pending instances | |
153 | of the signal are ignored and discarded. | |
154 | .Pp | |
155 | Options may be specified by setting | |
156 | .Em sa_flags . | |
157 | If the | |
158 | .Dv SA_NOCLDSTOP | |
159 | bit is set when installing a catching function | |
160 | for the | |
161 | .Dv SIGCHLD | |
162 | signal, | |
163 | the | |
164 | .Dv SIGCHLD | |
165 | signal will be generated only when a child process exits, | |
166 | not when a child process stops. | |
167 | Further, if the | |
168 | .Dv SA_ONSTACK | |
169 | bit is set in | |
170 | .Em sa_flags , | |
171 | the system will deliver the signal to the process on a | |
172 | .Em "signal stack" , | |
173 | specified with | |
174 | .Xr sigstack 2 . | |
175 | .Pp | |
176 | If a signal is caught during the system calls listed below, | |
177 | the call may be forced to terminate | |
178 | with the error | |
179 | .Dv EINTR , | |
180 | or the call may be restarted. | |
181 | Restart of pending calls is requested | |
182 | by setting the | |
183 | .Dv SA_RESTART | |
184 | bit in | |
185 | .Ar sa_flags . | |
186 | The affected system calls include | |
187 | .Xr read 2 , | |
188 | .Xr write 2 , | |
189 | .Xr sendto 2 , | |
190 | .Xr recvfrom 2 , | |
191 | .Xr sendmsg 2 | |
192 | and | |
193 | .Xr recvmsg 2 | |
194 | on a communications channel or a slow device (such as a terminal, | |
195 | but not a regular file) | |
196 | and during a | |
197 | .Xr wait 2 | |
198 | or | |
199 | .Xr ioctl 2 . | |
200 | However, calls that have already committed are not restarted, | |
201 | but instead return a partial success (for example, a short read count). | |
202 | .Pp | |
203 | After a | |
204 | .Xr fork 2 | |
205 | or | |
206 | .Xr vfork 2 | |
207 | all signals, the signal mask, the signal stack, | |
208 | and the restart/interrupt flags are inherited by the child. | |
209 | .Pp | |
210 | .Xr Execve 2 | |
211 | reinstates the default | |
212 | action for all signals which were caught and | |
213 | resets all signals to be caught on the user stack. | |
214 | Ignored signals remain ignored; | |
215 | the signal mask remains the same; | |
216 | signals that restart pending system calls continue to do so. | |
217 | .Pp | |
218 | The following is a list of all signals | |
219 | with names as in the include file | |
220 | .Aq Pa signal.h : | |
221 | .Bl -column SIGVTALARMXX "create core imagexxx" | |
222 | .It Sy " NAME " " Default Action " " Description" | |
223 | .It Dv SIGHUP No " terminate process" " terminal line hangup" | |
224 | .It Dv SIGINT No " terminate process" " interrupt program" | |
225 | .It Dv SIGQUIT No " create core image" " quit program" | |
226 | .It Dv SIGILL No " create core image" " illegal instruction" | |
227 | .It Dv SIGTRAP No " create core image" " trace trap" | |
228 | .It Dv SIGABRT No " create core image" Xr abort 2 | |
229 | call (formerly | |
230 | .Dv SIGIOT ) | |
231 | .It Dv SIGEMT No " create core image" " emulate instruction executed" | |
232 | .It Dv SIGFPE No " create core image" " floating-point exception" | |
233 | .It Dv SIGKILL No " terminate process" " kill program" | |
234 | .It Dv SIGBUS No " create core image" " bus error" | |
235 | .It Dv SIGSEGV No " create core image" " segmentation violation" | |
236 | .It Dv SIGSYS No " create core image" " system call given invalid argument" | |
237 | .It Dv SIGPIPE No " terminate process" " write on a pipe with no reader" | |
238 | .It Dv SIGALRM No " terminate process" " real-time timer expired" | |
239 | .It Dv SIGTERM No " terminate process" " software termination signal" | |
240 | .It Dv SIGURG No " discard signal" " urgent condition present on socket" | |
241 | .It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)" | |
242 | .It Dv SIGTSTP No " stop process" " stop signal generated from keyboard" | |
243 | .It Dv SIGCONT No " discard signal" " continue after stop" | |
244 | .It Dv SIGCHLD No " discard signal" " child status has changed" | |
245 | .It Dv SIGTTIN No " stop process" " background read attempted from control terminal" | |
246 | .It Dv SIGTTOU No " stop process" " background write attempted to control terminal" | |
247 | .It Dv SIGIO No " discard signal" Tn " I/O" | |
248 | is possible on a descriptor (see | |
249 | .Xr fcntl 2 ) | |
250 | .It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see" | |
251 | .Xr setrlimit 2 ) | |
252 | .It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see" | |
253 | .Xr setrlimit 2 ) | |
254 | .It Dv SIGVTALRM No " terminate process" " virtual time alarm (see" | |
255 | .Xr setitimer 2 ) | |
256 | .It Dv SIGPROF No " terminate process" " profiling timer alarm (see" | |
257 | .Xr setitimer 2 ) | |
258 | .It Dv SIGWINCH No " discard signal" " Window size change" | |
259 | .It Dv SIGINFO No " discard signal" " status request from keyboard" | |
260 | .It Dv SIGUSR1 No " terminate process" " User defined signal 1" | |
261 | .It Dv SIGUSR2 No " terminate process" " User defined signal 2" | |
262 | .El | |
263 | .Sh NOTE | |
264 | The mask specified in | |
265 | .Fa act | |
266 | is not allowed to block | |
267 | .Dv SIGKILL | |
268 | or | |
269 | .Dv SIGSTOP | |
270 | This is done silently by the system. | |
271 | .Sh RETURN VALUES | |
272 | A 0 value indicated that the call succeeded. A \-1 return value | |
273 | indicates an error occurred and | |
274 | .Va errno | |
275 | is set to indicated the reason. | |
276 | .Sh ERROR | |
277 | .Fn Sigaction | |
278 | will fail and no new signal handler will be installed if one | |
279 | of the following occurs: | |
280 | .Tw Er | |
281 | .Tl Bq Er EFAULT | |
282 | Either | |
283 | .Fa act | |
284 | or | |
285 | .Fa oact | |
286 | points to memory that is not a valid part of the process | |
287 | address space. | |
288 | .Tl Bq Er EINVAL | |
289 | .Fa Sig | |
290 | is not a valid signal number. | |
291 | .Tl Bq Er EINVAL | |
292 | An attempt is made to ignore or supply a handler for | |
293 | .Em SIGKIL | |
294 | or | |
295 | .Dv SIGSTOP | |
296 | .Tl | |
297 | .Sh STANDARD | |
298 | The | |
299 | .Nm sigaction | |
300 | function is defined by | |
301 | .St -p1003.1-88 . | |
302 | The | |
303 | .Dv SA_ONSTACK | |
304 | and | |
305 | .Dv SA_RESTART | |
306 | flags are Berkeley extensions, | |
307 | as are the signals, | |
308 | .Dv SIGTRAP , | |
309 | .Dv SIGEMT , | |
310 | .Dv SIGBUS , | |
311 | .Dv SIGSYS , | |
312 | .Dv SIGURG , | |
313 | .Dv SIGIO , | |
314 | .Dv SIGXCPU , | |
315 | .Dv SIGXFSZ , | |
316 | .Dv SIGVTALRM , | |
317 | .Dv SIGPROF , | |
318 | .Dv SIGWINCH , | |
319 | and | |
320 | .Dv SIGINFO . | |
321 | Most of those signals are available on most | |
322 | .Tn BSD Ns \-derived | |
323 | systems. | |
324 | .Sh SEE ALSO | |
325 | .Xr kill 1 , | |
326 | .Xr ptrace 2 , | |
327 | .Xr kill 2 , | |
328 | .Xr sigaction 2 , | |
329 | .Xr sigprocmask 2 , | |
330 | .Em sigsetops 2 , | |
331 | .Xr sigsuspend 2 , | |
332 | .Xr sigblock 2 , | |
333 | .Xr sigsetmask 2 , | |
334 | .Xr sigpause 2 , | |
335 | .Xr sigstack 2 , | |
336 | .Xr sigvec 2 , | |
337 | .Xr setjmp 3 , | |
338 | .Em siginterrupt 3 , | |
339 | .Xr tty 4 | |
340 | .Sh EXAMPLE | |
341 | On a | |
342 | .Tn VAX\-11, | |
343 | the handler routine can be declared: | |
344 | .Bd -literal -offset indent | |
345 | void handler(sig, code, scp) | |
346 | int sig, code; | |
347 | struct sigcontext *scp; | |
348 | .Ed | |
349 | .Pp | |
350 | Here | |
351 | .Fa sig | |
352 | is the signal number, into which the hardware faults and traps are | |
353 | mapped as defined below. | |
354 | .Em Code | |
355 | is a parameter that is either a constant | |
356 | as given below or the code provided by | |
357 | the hardware (Compatibility mode faults are distinguished from the | |
358 | other | |
359 | .Dv SIGILL | |
360 | traps by having | |
361 | .Dv PSL_CM | |
362 | set in the psl). | |
363 | .Fa Scp | |
364 | is a pointer to the | |
365 | .Fa sigcontext | |
366 | structure (defined in | |
367 | .Aq Pa signal.h ) , | |
368 | used to restore the context from before the signal. |