]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | '\" t |
2 | .\" Copyright (c) 1994,1995 Mike Battersby <mib@deakin.edu.au> | |
1130df60 | 3 | .\" and Copyright 2004, 2005 Michael Kerrisk <mtk-manpages@gmx.net> |
fea681da MK |
4 | .\" based on work by faith@cs.unc.edu |
5 | .\" | |
6 | .\" Permission is granted to make and distribute verbatim copies of this | |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
c13182ef | 14 | .\" |
fea681da MK |
15 | .\" Since the Linux kernel and libraries are constantly changing, this |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
c13182ef | 22 | .\" |
fea681da MK |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
25 | .\" | |
26 | .\" Modified, aeb, 960424 | |
27 | .\" Modified Fri Jan 31 17:31:20 1997 by Eric S. Raymond <esr@thyrsus.com> | |
28 | .\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff. | |
1cbdceb1 MK |
29 | .\" Modified Sat May 8 17:40:19 1999 by Matthew Wilcox |
30 | .\" add POSIX.1b signals | |
31 | .\" Modified Sat Dec 29 01:44:52 2001 by Evan Jones <ejones@uwaterloo.ca> | |
32 | .\" SA_ONSTACK | |
33 | .\" Modified 2004-11-11 by Michael Kerrisk <mtk-manpages@gmx.net> | |
34 | .\" Added mention of SIGCONT under SA_NOCLDSTOP | |
35 | .\" Added SA_NOCLDWAIT | |
b7769f32 MK |
36 | .\" Modified 2004-11-17 by Michael Kerrisk <mtk-manpages@gmx.net> |
37 | .\" Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags. | |
38 | .\" Formatting fixes | |
e1c77b39 | 39 | .\" 2004-12-09, mtk, added SI_TKILL + other minor changes |
00161f1b MK |
40 | .\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend() |
41 | .\" out of this page into separate pages. | |
fea681da | 42 | .\" |
d9343c5c | 43 | .TH SIGACTION 2 2005-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 44 | .SH NAME |
00161f1b | 45 | sigaction \- examine and change a signal action |
fea681da | 46 | .SH SYNOPSIS |
521bf584 | 47 | .nf |
fea681da | 48 | .B #include <signal.h> |
c13182ef | 49 | .sp |
fea681da | 50 | .BI "int sigaction(int " signum ", const struct sigaction *" act , |
521bf584 MK |
51 | .BI " struct sigaction *" oldact ); |
52 | .fi | |
fea681da MK |
53 | .SH DESCRIPTION |
54 | The | |
b7769f32 | 55 | .BR sigaction () |
fea681da MK |
56 | system call is used to change the action taken by a process on |
57 | receipt of a specific signal. | |
58 | .PP | |
59 | .I signum | |
60 | specifies the signal and can be any valid signal except | |
61 | .B SIGKILL | |
62 | and | |
63 | .BR SIGSTOP . | |
64 | .PP | |
65 | If | |
66 | .I act | |
67 | is non\-null, the new action for signal | |
68 | .I signum | |
69 | is installed from | |
70 | .IR act . | |
71 | If | |
72 | .I oldact | |
73 | is non\-null, the previous action is saved in | |
74 | .IR oldact . | |
75 | .PP | |
76 | The | |
b7769f32 | 77 | .I sigaction |
fea681da MK |
78 | structure is defined as something like |
79 | .sp | |
80 | .RS | |
81 | .nf | |
82 | struct sigaction { | |
521bf584 MK |
83 | void (*sa_handler)(int); |
84 | void (*sa_sigaction)(int, siginfo_t *, void *); | |
85 | sigset_t sa_mask; | |
86 | int sa_flags; | |
87 | void (*sa_restorer)(void); | |
fea681da MK |
88 | } |
89 | .fi | |
90 | .RE | |
91 | .PP | |
e9496f74 | 92 | On some architectures a union is involved: do not assign to both |
fea681da MK |
93 | .I sa_handler |
94 | and | |
95 | .IR sa_sigaction . | |
96 | .PP | |
97 | The | |
98 | .I sa_restorer | |
99 | element is obsolete and should not be used. | |
100 | POSIX does not specify a | |
101 | .I sa_restorer | |
102 | element. | |
103 | .PP | |
104 | .I sa_handler | |
105 | specifies the action to be associated with | |
106 | .I signum | |
107 | and may be | |
108 | .B SIG_DFL | |
c13182ef | 109 | for the default action, |
fea681da MK |
110 | .B SIG_IGN |
111 | to ignore this signal, or a pointer to a signal handling function. | |
112 | This function receives the signal number as its only argument. | |
113 | .PP | |
00161f1b MK |
114 | If |
115 | .B SA_SIGINFO | |
116 | is specified in | |
c13182ef | 117 | .IR sa_flags , |
00161f1b | 118 | then |
fea681da | 119 | .I sa_sigaction |
00161f1b MK |
120 | (instead of |
121 | .IR sa_handler ) | |
122 | specifies the signal-handling function for | |
fea681da MK |
123 | .IR signum . |
124 | This function receives the signal number as its first argument, a | |
125 | pointer to a | |
126 | .I siginfo_t | |
127 | as its second argument and a pointer to a | |
128 | .I ucontext_t | |
129 | (cast to void *) as its third argument. | |
130 | .PP | |
131 | .I sa_mask | |
132 | gives a mask of signals which should be blocked during execution of | |
c13182ef MK |
133 | the signal handler. |
134 | In addition, the signal which triggered the handler | |
fea681da MK |
135 | will be blocked, unless the |
136 | .B SA_NODEFER | |
b7769f32 | 137 | flag is used. |
fea681da MK |
138 | .PP |
139 | .I sa_flags | |
d9bfdb9c | 140 | specifies a set of flags which modify the behavior of the signal handling |
c13182ef MK |
141 | process. |
142 | It is formed by the bitwise OR of zero or more of the following: | |
fea681da MK |
143 | .RS |
144 | .TP | |
145 | .B SA_NOCLDSTOP | |
146 | If | |
147 | .I signum | |
148 | is | |
1cbdceb1 MK |
149 | .BR SIGCHLD , |
150 | do not receive notification when child processes stop (i.e., when they | |
151 | receive one of | |
fea681da MK |
152 | .BR SIGSTOP ", " SIGTSTP ", " SIGTTIN |
153 | or | |
1cbdceb1 MK |
154 | .BR SIGTTOU ) |
155 | or resume (i.e., they receive | |
156 | .BR SIGCONT ) | |
157 | (see | |
158 | .BR wait (2)). | |
fea681da | 159 | .TP |
1cbdceb1 MK |
160 | .B SA_NOCLDWAIT |
161 | (Linux 2.6 and later) | |
162 | .\" To be precise: Linux 2.5.60 -- MTK | |
163 | If | |
164 | .I signum | |
165 | is | |
166 | .BR SIGCHLD , | |
167 | do not transform children into zombies when they terminate. | |
168 | See also | |
b7769f32 | 169 | .BR waitpid (2). |
1cbdceb1 MK |
170 | .TP |
171 | .B SA_RESETHAND | |
fea681da MK |
172 | Restore the signal action to the default state once the signal handler |
173 | has been called. | |
1cbdceb1 MK |
174 | .B SA_ONESHOT |
175 | is an obsolete, non-standard synonym for this flag. | |
fea681da MK |
176 | .TP |
177 | .BR SA_ONSTACK | |
c13182ef | 178 | Call the signal handler on an alternate signal stack provided by |
fea681da MK |
179 | .BR sigaltstack (2). |
180 | If an alternate stack is not available, the default stack will be used. | |
181 | .TP | |
182 | .B SA_RESTART | |
d9bfdb9c | 183 | Provide behavior compatible with BSD signal semantics by making certain |
fea681da MK |
184 | system calls restartable across signals. |
185 | .TP | |
1cbdceb1 | 186 | .B SA_NODEFER |
fea681da MK |
187 | Do not prevent the signal from being received from within its own signal |
188 | handler. | |
1cbdceb1 MK |
189 | .B SA_NOMASK |
190 | is an obsolete, non-standard synonym for this flag. | |
fea681da MK |
191 | .TP |
192 | .B SA_SIGINFO | |
c13182ef MK |
193 | The signal handler takes 3 arguments, not one. |
194 | In this case, | |
fea681da MK |
195 | .I sa_sigaction |
196 | should be set instead of | |
197 | .IR sa_handler . | |
b7769f32 MK |
198 | (The |
199 | .I sa_sigaction | |
200 | field was added in Linux 2.1.86.) | |
fea681da MK |
201 | .RE |
202 | .PP | |
203 | The | |
204 | .I siginfo_t | |
205 | parameter to | |
206 | .I sa_sigaction | |
207 | is a struct with the following elements | |
208 | .sp | |
209 | .RS | |
210 | .nf | |
fea681da | 211 | siginfo_t { |
7295b7ed MK |
212 | int si_signo; /* Signal number */ |
213 | int si_errno; /* An errno value */ | |
214 | int si_code; /* Signal code */ | |
215 | pid_t si_pid; /* Sending process ID */ | |
216 | uid_t si_uid; /* Real user ID of sending process */ | |
217 | int si_status; /* Exit value or signal */ | |
218 | clock_t si_utime; /* User time consumed */ | |
219 | clock_t si_stime; /* System time consumed */ | |
220 | sigval_t si_value; /* Signal value */ | |
221 | int si_int; /* POSIX.1b signal */ | |
222 | void *si_ptr; /* POSIX.1b signal */ | |
223 | void *si_addr; /* Memory location which caused fault */ | |
224 | int si_band; /* Band event */ | |
225 | int si_fd; /* File descriptor */ | |
fea681da MK |
226 | } |
227 | .fi | |
228 | .RE | |
229 | ||
230 | .IR si_signo ", " si_errno " and " si_code | |
231 | are defined for all signals. | |
c625361f MK |
232 | .RI ( si_signo |
233 | is unused on Linux.) | |
fea681da | 234 | The rest of the struct may be a union, so that one should only |
2e519bf2 MK |
235 | read the fields that are meaningful for the given signal: |
236 | .IP * 2 | |
b7769f32 MK |
237 | POSIX.1b signals and |
238 | .B SIGCHLD | |
239 | fill in | |
fea681da | 240 | .IR si_pid " and " si_uid . |
c13182ef | 241 | .BR |
2e519bf2 | 242 | .IP * |
b7769f32 MK |
243 | .B SIGCHLD |
244 | also fills in | |
fea681da | 245 | .IR si_status ", " si_utime " and " si_stime . |
2e519bf2 | 246 | .IP * |
fea681da MK |
247 | .IR si_int " and " si_ptr |
248 | are specified by the sender of the POSIX.1b signal. | |
2e519bf2 MK |
249 | See |
250 | .BR sigqueue (2) | |
251 | for more details. | |
252 | .IP * | |
c13182ef | 253 | .BR SIGILL , |
b7769f32 | 254 | .BR SIGFPE , |
c13182ef | 255 | .BR SIGSEGV , |
b7769f32 MK |
256 | and |
257 | .B SIGBUS | |
258 | fill in | |
fea681da MK |
259 | .I si_addr |
260 | with the address of the fault. | |
b7769f32 MK |
261 | .B SIGPOLL |
262 | fills in | |
fea681da | 263 | .IR si_band " and " si_fd . |
2e519bf2 | 264 | .PP |
fea681da | 265 | .I si_code |
c13182ef MK |
266 | indicates why this signal was sent. |
267 | It is a value, not a bitmask. | |
268 | The values which are possible for any signal are listed in this table: | |
fea681da MK |
269 | .TS |
270 | tab(:) allbox; | |
271 | c s | |
272 | l l. | |
273 | \fIsi_code\fR | |
274 | Value:Signal origin | |
8fc3da7e | 275 | SI_USER:kill(2) or raise(3) |
fea681da | 276 | SI_KERNEL:The kernel |
0bfa087b | 277 | SI_QUEUE:sigqueue(2) |
e1c77b39 MK |
278 | SI_TIMER:POSIX timer expired |
279 | SI_MESGQ:POSIX message queue state changed (since Linux 2.6.6) | |
fea681da MK |
280 | SI_ASYNCIO:AIO completed |
281 | SI_SIGIO:queued SIGIO | |
0bfa087b | 282 | SI_TKILL:tkill(2) or tgkill(2) (since Linux 2.4.19) |
92057f4d | 283 | .\" SI_DETHREAD is defined in 2.6.9 sources, but isn't implemented |
c13182ef | 284 | .\" It appears to have been an idea that was tried during 2.5.6 |
92057f4d | 285 | .\" through to 2.5.24 and then was backed out. |
fea681da MK |
286 | .TE |
287 | ||
288 | .TS | |
289 | tab(:) allbox; | |
290 | c s | |
291 | l l. | |
292 | SIGILL | |
293 | ILL_ILLOPC:illegal opcode | |
294 | ILL_ILLOPN:illegal operand | |
295 | ILL_ILLADR:illegal addressing mode | |
296 | ILL_ILLTRP:illegal trap | |
297 | ILL_PRVOPC:privileged opcode | |
298 | ILL_PRVREG:privileged register | |
299 | ILL_COPROC:coprocessor error | |
300 | ILL_BADSTK:internal stack error | |
301 | .TE | |
302 | ||
303 | .TS | |
304 | tab(:) allbox; | |
305 | c s | |
306 | l l. | |
307 | SIGFPE | |
308 | FPE_INTDIV:integer divide by zero | |
309 | FPE_INTOVF:integer overflow | |
310 | FPE_FLTDIV:floating point divide by zero | |
311 | FPE_FLTOVF:floating point overflow | |
312 | FPE_FLTUND:floating point underflow | |
313 | FPE_FLTRES:floating point inexact result | |
314 | FPE_FLTINV:floating point invalid operation | |
315 | FPE_FLTSUB:subscript out of range | |
316 | .TE | |
317 | ||
318 | .TS | |
319 | tab(:) allbox; | |
320 | c s | |
321 | l l. | |
322 | SIGSEGV | |
323 | SEGV_MAPERR:address not mapped to object | |
324 | SEGV_ACCERR:invalid permissions for mapped object | |
325 | .TE | |
326 | ||
327 | .TS | |
328 | tab(:) allbox; | |
329 | c s | |
330 | l l. | |
331 | SIGBUS | |
332 | BUS_ADRALN:invalid address alignment | |
333 | BUS_ADRERR:non-existent physical address | |
334 | BUS_OBJERR:object specific hardware error | |
335 | .TE | |
336 | ||
337 | .TS | |
338 | tab(:) allbox; | |
339 | c s | |
340 | l l. | |
341 | SIGTRAP | |
342 | TRAP_BRKPT:process breakpoint | |
343 | TRAP_TRACE:process trace trap | |
344 | .TE | |
345 | ||
346 | .TS | |
347 | tab(:) allbox; | |
348 | c s | |
349 | l l. | |
350 | SIGCHLD | |
351 | CLD_EXITED:child has exited | |
352 | CLD_KILLED:child was killed | |
353 | CLD_DUMPED:child terminated abnormally | |
354 | CLD_TRAPPED:traced child has trapped | |
355 | CLD_STOPPED:child has stopped | |
f8c31d60 | 356 | CLD_CONTINUED:stopped child has continued (since Linux 2.6.9) |
fea681da MK |
357 | .TE |
358 | ||
359 | .TS | |
360 | tab(:) allbox; | |
361 | c s | |
362 | l l. | |
363 | SIGPOLL | |
364 | POLL_IN:data input available | |
365 | POLL_OUT:output buffers available | |
366 | POLL_MSG:input message available | |
367 | POLL_ERR:i/o error | |
368 | POLL_PRI:high priority input available | |
369 | POLL_HUP:device disconnected | |
370 | .TE | |
fea681da | 371 | .SH "RETURN VALUE" |
00161f1b MK |
372 | .BR sigaction () |
373 | returns 0 on success and \-1 on error. | |
fea681da MK |
374 | .SH ERRORS |
375 | .TP | |
376 | .B EFAULT | |
00161f1b MK |
377 | .IR act " or " oldact |
378 | points to memory which is not a valid part of the process address space. | |
fea681da MK |
379 | .TP |
380 | .B EINVAL | |
c13182ef MK |
381 | An invalid signal was specified. |
382 | This will also be generated if an attempt | |
fea681da MK |
383 | is made to change the action for |
384 | .BR SIGKILL " or " SIGSTOP ", " | |
00161f1b | 385 | which cannot be caught or ignored. |
2dd578fd MK |
386 | .SH "CONFORMING TO" |
387 | POSIX.1-2001, SVr4. | |
388 | .\" SVr4 does not document the EINTR condition. | |
fea681da | 389 | .SH NOTES |
fea681da | 390 | .PP |
d9bfdb9c | 391 | According to POSIX, the behavior of a process is undefined after it |
b7769f32 MK |
392 | ignores a |
393 | .BR SIGFPE , | |
394 | .BR SIGILL , | |
395 | or | |
396 | .BR SIGSEGV | |
397 | signal that was not generated by | |
0bfa087b | 398 | .BR kill (2) |
b7769f32 | 399 | or |
0bfa087b | 400 | .BR raise (3). |
fea681da | 401 | Integer division by zero has undefined result. |
b7769f32 MK |
402 | On some architectures it will generate a |
403 | .B SIGFPE | |
404 | signal. | |
8bd58774 MK |
405 | (Also dividing the most negative integer by \-1 may generate |
406 | .BR SIGFPE .) | |
fea681da MK |
407 | Ignoring this signal might lead to an endless loop. |
408 | .PP | |
b7769f32 MK |
409 | POSIX.1-1990 disallowed setting the action for |
410 | .B SIGCHLD | |
411 | to | |
412 | .BR SIG_IGN . | |
413 | POSIX.1-2001 allows this possibility, so that ignoring | |
414 | .B SIGCHLD | |
415 | can be used to prevent the creation of zombies (see | |
416 | .BR wait (2)). | |
d9bfdb9c | 417 | Nevertheless, the historical BSD and System V behaviors for ignoring |
b7769f32 MK |
418 | .B SIGCHLD |
419 | differ, so that the only completely portable method of ensuring that | |
420 | terminated children do not become zombies is to catch the | |
421 | .B SIGCHLD | |
422 | signal and perform a | |
423 | .BR wait (2) | |
424 | or similar. | |
fea681da | 425 | .PP |
b7769f32 | 426 | POSIX.1-1990 only specified |
fea681da | 427 | .BR SA_NOCLDSTOP . |
b7769f32 MK |
428 | POSIX.1-2001 added |
429 | .BR SA_NOCLDWAIT , | |
430 | .BR SA_RESETHAND , | |
431 | .BR SA_NODEFER , | |
432 | and | |
433 | .BR SA_SIGINFO . | |
434 | Use of these latter values in | |
fea681da | 435 | .I sa_flags |
b7769f32 MK |
436 | may be less portable in applications intended for older |
437 | Unix implementations. | |
438 | .PP | |
439 | Support for | |
440 | .B SA_SIGINFO | |
441 | was added in Linux 2.2. | |
fea681da MK |
442 | .PP |
443 | The | |
444 | .B SA_RESETHAND | |
445 | flag is compatible with the SVr4 flag of the same name. | |
446 | .PP | |
447 | The | |
448 | .B SA_NODEFER | |
449 | flag is compatible with the SVr4 flag of the same name under kernels | |
c13182ef MK |
450 | 1.3.9 and newer. |
451 | On older kernels the Linux implementation | |
fea681da MK |
452 | allowed the receipt of any signal, not just the one we are installing |
453 | (effectively overriding any | |
454 | .I sa_mask | |
455 | settings). | |
00161f1b MK |
456 | .\".PP |
457 | .\"The | |
458 | .\".BR SA_RESETHAND " and " SA_NODEFER | |
459 | .\"names for SVr4 compatibility are present only in library versions 3.0.9 | |
460 | .\"and greater. | |
fea681da | 461 | .PP |
b7769f32 | 462 | .BR sigaction () |
fea681da | 463 | can be called with a null second argument to query the current signal |
c13182ef MK |
464 | handler. |
465 | It can also be used to check whether a given signal is valid for | |
fea681da MK |
466 | the current machine by calling it with null second and third arguments. |
467 | .PP | |
c13182ef | 468 | It is not possible to block |
00161f1b MK |
469 | .BR SIGKILL " or " SIGSTOP |
470 | (by specifying them in | |
471 | .IR sa_mask ). | |
472 | Attempts to do so are silently ignored. | |
473 | .PP | |
fea681da MK |
474 | See |
475 | .BR sigsetops (3) | |
476 | for details on manipulating signal sets. | |
2e519bf2 MK |
477 | .PP |
478 | See | |
479 | .BR signal (7) | |
480 | for a list of the async-signal-safe functions that can be | |
481 | safely called inside from inside a signal handler. | |
4a19cb8c MK |
482 | .SS Undocumented |
483 | Before the introduction of | |
484 | .B SA_SIGINFO | |
485 | it was also possible to get some additional information, | |
486 | namely by using a | |
487 | .I sa_handler | |
488 | with second argument of type | |
489 | .IR "struct sigcontext". | |
490 | See the relevant kernel sources for details. | |
491 | This use is obsolete now. | |
00161f1b MK |
492 | .SH BUGS |
493 | In kernels up to and including 2.6.13, specifying | |
494 | .B SA_NODEFER | |
495 | in | |
496 | .I sa_flags | |
c13182ef | 497 | preventing not only the delivered signal from being masked during |
00161f1b MK |
498 | execution of the handler, but also the signals specified in |
499 | .IR sa_mask . | |
500 | This bug is was fixed in kernel 2.6.14. | |
af5267b2 MK |
501 | .SH EXAMPLE |
502 | See | |
503 | .BR mprotect (2). | |
fea681da MK |
504 | .SH "SEE ALSO" |
505 | .BR kill (1), | |
506 | .BR kill (2), | |
fea681da MK |
507 | .BR pause (2), |
508 | .BR sigaltstack (2), | |
509 | .BR signal (2), | |
00161f1b MK |
510 | .BR sigpending (2), |
511 | .BR sigprocmask (2), | |
1cbdceb1 | 512 | .BR sigqueue (2), |
00161f1b | 513 | .BR sigsuspend (2), |
b7769f32 | 514 | .BR wait (2), |
1cbdceb1 | 515 | .BR killpg (3), |
fea681da MK |
516 | .BR raise (3), |
517 | .BR siginterrupt (3), | |
518 | .BR sigsetops (3), | |
30ecea55 | 519 | .BR sigvec (3), |
e1a9bc1b | 520 | .BR core (5), |
fea681da | 521 | .BR signal (7) |