Commit | Line | Data |
---|---|---|
15715acc KB |
1 | .\" Copyright (c) 1980, 1990, 1993 |
2 | .\" The Regents of the University of California. All rights reserved. | |
87714767 | 3 | .\" |
ad787160 C |
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. | |
87714767 | 19 | .\" |
ad787160 C |
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. | |
87714767 | 31 | .\" |
ed554bc5 | 32 | .\" @(#)sigaction.2 8.2 (Berkeley) 4/3/94 |
ad787160 | 33 | .\" |
ed554bc5 | 34 | .Dd April 3, 1994 |
e17b717a | 35 | .Dt SIGACTION 2 |
faf7e3e0 | 36 | .Os |
e17b717a CL |
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 | |
87714767 | 51 | The system defines a set of signals that may be delivered to a process. |
1435cb8b | 52 | Signal delivery resembles the occurrence of a hardware interrupt: |
87714767 MK |
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 | |
e17b717a | 55 | .Em handler |
87714767 | 56 | to which a signal is delivered, or specify that a signal is to be |
e17b717a | 57 | .Em ignored . |
87714767 MK |
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 | |
e17b717a | 61 | .Em blocked , |
87714767 | 62 | in which case its delivery is postponed until it is |
e17b717a | 63 | .Em unblocked . |
87714767 MK |
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 | |
e17b717a CL |
69 | .Em "signal stack" . |
70 | .Pp | |
87714767 MK |
71 | Signal routines execute with the signal that caused their |
72 | invocation | |
e17b717a | 73 | .Em blocked , |
87714767 MK |
74 | but other signals may yet occur. |
75 | A global | |
e17b717a | 76 | .Em "signal mask" |
87714767 MK |
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 | |
e17b717a | 81 | .Xr sigprocmask 2 |
87714767 | 82 | call, or when a signal is delivered to the process. |
e17b717a | 83 | .Pp |
87714767 MK |
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 | |
e17b717a | 88 | .Em blocked |
87714767 MK |
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 | |
e17b717a | 98 | .Xr sigpending 2 |
87714767 MK |
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. | |
e17b717a | 109 | .Pp |
87714767 MK |
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 | |
e17b717a | 113 | .Xr sigprocmask |
87714767 MK |
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. | |
e17b717a CL |
118 | .Pp |
119 | .Fn Sigaction | |
87714767 MK |
120 | assigns an action for a specific signal. |
121 | If | |
e17b717a | 122 | .Fa act |
87714767 | 123 | is non-zero, it |
e17b717a CL |
124 | specifies an action |
125 | .Pf ( Dv SIG_DFL , | |
126 | .Dv SIG_IGN , | |
127 | or a handler routine) and mask | |
87714767 MK |
128 | to be used when delivering the specified signal. |
129 | If | |
e17b717a | 130 | .Fa oact |
87714767 MK |
131 | is non-zero, the previous handling information for the signal |
132 | is returned to the user. | |
e17b717a | 133 | .Pp |
87714767 MK |
134 | Once a signal handler is installed, it remains installed |
135 | until another | |
e17b717a | 136 | .Fn sigaction |
87714767 | 137 | call is made, or an |
e17b717a | 138 | .Xr execve 2 |
87714767 | 139 | is performed. |
e17b717a CL |
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; | |
87714767 MK |
146 | no action; stopping the process; or continuing the process. |
147 | See the signal list below for each signal's default action. | |
148 | If | |
e17b717a CL |
149 | .Fa sa_handler |
150 | is | |
1435cb8b KM |
151 | .Dv SIG_DFL , |
152 | the default action for the signal is to discard the signal, | |
153 | and if a signal is pending, | |
154 | the pending signal is discarded even if the signal is masked. | |
155 | If | |
156 | .Fa sa_handler | |
157 | is set to | |
e17b717a CL |
158 | .Dv SIG_IGN |
159 | current and pending instances | |
160 | of the signal are ignored and discarded. | |
161 | .Pp | |
87714767 | 162 | Options may be specified by setting |
e17b717a CL |
163 | .Em sa_flags . |
164 | If the | |
165 | .Dv SA_NOCLDSTOP | |
166 | bit is set when installing a catching function | |
167 | for the | |
168 | .Dv SIGCHLD | |
169 | signal, | |
170 | the | |
171 | .Dv SIGCHLD | |
172 | signal will be generated only when a child process exits, | |
87714767 | 173 | not when a child process stops. |
e17b717a CL |
174 | Further, if the |
175 | .Dv SA_ONSTACK | |
176 | bit is set in | |
177 | .Em sa_flags , | |
87714767 | 178 | the system will deliver the signal to the process on a |
e17b717a | 179 | .Em "signal stack" , |
87714767 | 180 | specified with |
1435cb8b | 181 | .Xr sigstack 2 . |
e17b717a CL |
182 | .Pp |
183 | If a signal is caught during the system calls listed below, | |
184 | the call may be forced to terminate | |
185 | with the error | |
186 | .Dv EINTR , | |
1435cb8b | 187 | the call may return with a data transfer shorter than requested, |
87714767 MK |
188 | or the call may be restarted. |
189 | Restart of pending calls is requested | |
e17b717a CL |
190 | by setting the |
191 | .Dv SA_RESTART | |
192 | bit in | |
193 | .Ar sa_flags . | |
87714767 | 194 | The affected system calls include |
1435cb8b | 195 | .Xr open 2 , |
e17b717a CL |
196 | .Xr read 2 , |
197 | .Xr write 2 , | |
198 | .Xr sendto 2 , | |
199 | .Xr recvfrom 2 , | |
200 | .Xr sendmsg 2 | |
87714767 | 201 | and |
e17b717a | 202 | .Xr recvmsg 2 |
87714767 MK |
203 | on a communications channel or a slow device (such as a terminal, |
204 | but not a regular file) | |
205 | and during a | |
e17b717a | 206 | .Xr wait 2 |
87714767 | 207 | or |
e17b717a | 208 | .Xr ioctl 2 . |
87714767 MK |
209 | However, calls that have already committed are not restarted, |
210 | but instead return a partial success (for example, a short read count). | |
e17b717a | 211 | .Pp |
87714767 | 212 | After a |
e17b717a | 213 | .Xr fork 2 |
87714767 | 214 | or |
e17b717a | 215 | .Xr vfork 2 |
87714767 | 216 | all signals, the signal mask, the signal stack, |
e17b717a CL |
217 | and the restart/interrupt flags are inherited by the child. |
218 | .Pp | |
219 | .Xr Execve 2 | |
220 | reinstates the default | |
221 | action for all signals which were caught and | |
87714767 MK |
222 | resets all signals to be caught on the user stack. |
223 | Ignored signals remain ignored; | |
224 | the signal mask remains the same; | |
225 | signals that restart pending system calls continue to do so. | |
e17b717a | 226 | .Pp |
87714767 MK |
227 | The following is a list of all signals |
228 | with names as in the include file | |
e17b717a CL |
229 | .Aq Pa signal.h : |
230 | .Bl -column SIGVTALARMXX "create core imagexxx" | |
87af7cb9 | 231 | .It Sy " NAME " " Default Action " " Description" |
e17b717a CL |
232 | .It Dv SIGHUP No " terminate process" " terminal line hangup" |
233 | .It Dv SIGINT No " terminate process" " interrupt program" | |
234 | .It Dv SIGQUIT No " create core image" " quit program" | |
235 | .It Dv SIGILL No " create core image" " illegal instruction" | |
236 | .It Dv SIGTRAP No " create core image" " trace trap" | |
237 | .It Dv SIGABRT No " create core image" Xr abort 2 | |
238 | call (formerly | |
239 | .Dv SIGIOT ) | |
240 | .It Dv SIGEMT No " create core image" " emulate instruction executed" | |
241 | .It Dv SIGFPE No " create core image" " floating-point exception" | |
242 | .It Dv SIGKILL No " terminate process" " kill program" | |
243 | .It Dv SIGBUS No " create core image" " bus error" | |
244 | .It Dv SIGSEGV No " create core image" " segmentation violation" | |
245 | .It Dv SIGSYS No " create core image" " system call given invalid argument" | |
246 | .It Dv SIGPIPE No " terminate process" " write on a pipe with no reader" | |
247 | .It Dv SIGALRM No " terminate process" " real-time timer expired" | |
248 | .It Dv SIGTERM No " terminate process" " software termination signal" | |
249 | .It Dv SIGURG No " discard signal" " urgent condition present on socket" | |
250 | .It Dv SIGSTOP No " stop process" " stop (cannot be caught or ignored)" | |
251 | .It Dv SIGTSTP No " stop process" " stop signal generated from keyboard" | |
252 | .It Dv SIGCONT No " discard signal" " continue after stop" | |
253 | .It Dv SIGCHLD No " discard signal" " child status has changed" | |
254 | .It Dv SIGTTIN No " stop process" " background read attempted from control terminal" | |
255 | .It Dv SIGTTOU No " stop process" " background write attempted to control terminal" | |
256 | .It Dv SIGIO No " discard signal" Tn " I/O" | |
257 | is possible on a descriptor (see | |
258 | .Xr fcntl 2 ) | |
259 | .It Dv SIGXCPU No " terminate process" " cpu time limit exceeded (see" | |
260 | .Xr setrlimit 2 ) | |
261 | .It Dv SIGXFSZ No " terminate process" " file size limit exceeded (see" | |
262 | .Xr setrlimit 2 ) | |
263 | .It Dv SIGVTALRM No " terminate process" " virtual time alarm (see" | |
264 | .Xr setitimer 2 ) | |
265 | .It Dv SIGPROF No " terminate process" " profiling timer alarm (see" | |
266 | .Xr setitimer 2 ) | |
267 | .It Dv SIGWINCH No " discard signal" " Window size change" | |
268 | .It Dv SIGINFO No " discard signal" " status request from keyboard" | |
269 | .It Dv SIGUSR1 No " terminate process" " User defined signal 1" | |
270 | .It Dv SIGUSR2 No " terminate process" " User defined signal 2" | |
271 | .El | |
272 | .Sh NOTE | |
87714767 | 273 | The mask specified in |
e17b717a CL |
274 | .Fa act |
275 | is not allowed to block | |
276 | .Dv SIGKILL | |
277 | or | |
1435cb8b | 278 | .Dv SIGSTOP . |
87714767 | 279 | This is done silently by the system. |
e17b717a | 280 | .Sh RETURN VALUES |
87714767 MK |
281 | A 0 value indicated that the call succeeded. A \-1 return value |
282 | indicates an error occurred and | |
e17b717a | 283 | .Va errno |
87714767 | 284 | is set to indicated the reason. |
1435cb8b KM |
285 | .Sh EXAMPLE |
286 | The handler routine can be declared: | |
287 | .Bd -literal -offset indent | |
288 | void handler(sig, code, scp) | |
289 | int sig, code; | |
290 | struct sigcontext *scp; | |
291 | .Ed | |
292 | .Pp | |
293 | Here | |
294 | .Fa sig | |
295 | is the signal number, into which the hardware faults and traps are | |
296 | mapped. | |
87af7cb9 | 297 | .Fa Code |
1435cb8b KM |
298 | is a parameter that is either a constant |
299 | or the code provided by | |
300 | the hardware. | |
301 | .Fa Scp | |
302 | is a pointer to the | |
303 | .Fa sigcontext | |
304 | structure (defined in | |
305 | .Aq Pa signal.h ) , | |
306 | used to restore the context from before the signal. | |
307 | .Sh ERRORS | |
e17b717a | 308 | .Fn Sigaction |
87714767 MK |
309 | will fail and no new signal handler will be installed if one |
310 | of the following occurs: | |
1435cb8b KM |
311 | .Bl -tag -width Er |
312 | .It Bq Er EFAULT | |
87714767 | 313 | Either |
e17b717a | 314 | .Fa act |
87714767 | 315 | or |
e17b717a | 316 | .Fa oact |
87714767 MK |
317 | points to memory that is not a valid part of the process |
318 | address space. | |
1435cb8b | 319 | .It Bq Er EINVAL |
e17b717a | 320 | .Fa Sig |
87714767 | 321 | is not a valid signal number. |
1435cb8b | 322 | .It Bq Er EINVAL |
e17b717a | 323 | An attempt is made to ignore or supply a handler for |
87af7cb9 | 324 | .Dv SIGKILL |
e17b717a | 325 | or |
87af7cb9 | 326 | .Dv SIGSTOP . |
1435cb8b | 327 | .El |
87af7cb9 | 328 | .Sh STANDARDS |
e17b717a | 329 | The |
faf7e3e0 | 330 | .Nm sigaction |
e17b717a CL |
331 | function is defined by |
332 | .St -p1003.1-88 . | |
87714767 | 333 | The |
e17b717a CL |
334 | .Dv SA_ONSTACK |
335 | and | |
336 | .Dv SA_RESTART | |
337 | flags are Berkeley extensions, | |
338 | as are the signals, | |
339 | .Dv SIGTRAP , | |
340 | .Dv SIGEMT , | |
341 | .Dv SIGBUS , | |
342 | .Dv SIGSYS , | |
343 | .Dv SIGURG , | |
344 | .Dv SIGIO , | |
345 | .Dv SIGXCPU , | |
346 | .Dv SIGXFSZ , | |
347 | .Dv SIGVTALRM , | |
348 | .Dv SIGPROF , | |
349 | .Dv SIGWINCH , | |
350 | and | |
351 | .Dv SIGINFO . | |
1435cb8b | 352 | Those signals are available on most |
e17b717a CL |
353 | .Tn BSD Ns \-derived |
354 | systems. | |
355 | .Sh SEE ALSO | |
356 | .Xr kill 1 , | |
357 | .Xr ptrace 2 , | |
358 | .Xr kill 2 , | |
359 | .Xr sigaction 2 , | |
360 | .Xr sigprocmask 2 , | |
e17b717a CL |
361 | .Xr sigsuspend 2 , |
362 | .Xr sigblock 2 , | |
363 | .Xr sigsetmask 2 , | |
364 | .Xr sigpause 2 , | |
1435cb8b | 365 | .Xr sigstack 2 , |
e17b717a CL |
366 | .Xr sigvec 2 , |
367 | .Xr setjmp 3 , | |
1435cb8b | 368 | .Xr siginterrupt 3 , |
ed554bc5 | 369 | .Xr sigsetops 3 , |
e17b717a | 370 | .Xr tty 4 |