]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | '\" t |
2 | .\" Copyright (c) 1994,1995 Mike Battersby <mib@deakin.edu.au> | |
c11b1abf | 3 | .\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da MK |
4 | .\" based on work by faith@cs.unc.edu |
5 | .\" | |
93015253 | 6 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
7 | .\" Permission is granted to make and distribute verbatim copies of this |
8 | .\" manual provided the copyright notice and this permission notice are | |
9 | .\" preserved on all copies. | |
10 | .\" | |
11 | .\" Permission is granted to copy and distribute modified versions of this | |
12 | .\" manual under the conditions for verbatim copying, provided that the | |
13 | .\" entire resulting derived work is distributed under the terms of a | |
14 | .\" permission notice identical to this one. | |
c13182ef | 15 | .\" |
fea681da MK |
16 | .\" Since the Linux kernel and libraries are constantly changing, this |
17 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
18 | .\" responsibility for errors or omissions, or for damages resulting from | |
19 | .\" the use of the information contained herein. The author(s) may not | |
20 | .\" have taken the same level of care in the production of this manual, | |
21 | .\" which is licensed free of charge, as they might when working | |
22 | .\" professionally. | |
c13182ef | 23 | .\" |
fea681da MK |
24 | .\" Formatted or processed versions of this manual, if unaccompanied by |
25 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 26 | .\" %%%LICENSE_END |
fea681da MK |
27 | .\" |
28 | .\" Modified, aeb, 960424 | |
29 | .\" Modified Fri Jan 31 17:31:20 1997 by Eric S. Raymond <esr@thyrsus.com> | |
30 | .\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff. | |
1cbdceb1 MK |
31 | .\" Modified Sat May 8 17:40:19 1999 by Matthew Wilcox |
32 | .\" add POSIX.1b signals | |
33 | .\" Modified Sat Dec 29 01:44:52 2001 by Evan Jones <ejones@uwaterloo.ca> | |
34 | .\" SA_ONSTACK | |
c11b1abf | 35 | .\" Modified 2004-11-11 by Michael Kerrisk <mtk.manpages@gmail.com> |
1cbdceb1 MK |
36 | .\" Added mention of SIGCONT under SA_NOCLDSTOP |
37 | .\" Added SA_NOCLDWAIT | |
c11b1abf | 38 | .\" Modified 2004-11-17 by Michael Kerrisk <mtk.manpages@gmail.com> |
b7769f32 MK |
39 | .\" Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags. |
40 | .\" Formatting fixes | |
e1c77b39 | 41 | .\" 2004-12-09, mtk, added SI_TKILL + other minor changes |
00161f1b MK |
42 | .\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend() |
43 | .\" out of this page into separate pages. | |
665f1e69 MK |
44 | .\" 2010-06-11 Andi Kleen, add hwpoison signal extensions |
45 | .\" 2010-06-11 mtk, improvements to discussion of various siginfo_t fields. | |
3b4a59c4 KC |
46 | .\" 2015-01-17, Kees Cook <keescook@chromium.org> |
47 | .\" Added notes on ptrace SIGTRAP and SYS_SECCOMP. | |
fea681da | 48 | .\" |
460495ca | 49 | .TH SIGACTION 2 2015-08-08 "Linux" "Linux Programmer's Manual" |
fea681da | 50 | .SH NAME |
1545ed95 | 51 | sigaction, rt_sigaction \- examine and change a signal action |
fea681da | 52 | .SH SYNOPSIS |
521bf584 | 53 | .nf |
fea681da | 54 | .B #include <signal.h> |
c13182ef | 55 | .sp |
fea681da | 56 | .BI "int sigaction(int " signum ", const struct sigaction *" act , |
521bf584 MK |
57 | .BI " struct sigaction *" oldact ); |
58 | .fi | |
0f200f07 MK |
59 | .sp |
60 | .in -4n | |
61 | Feature Test Macro Requirements for glibc (see | |
62 | .BR feature_test_macros (7)): | |
63 | .in | |
64 | .sp | |
65 | .ad l | |
66 | .BR sigaction (): | |
67 | _POSIX_C_SOURCE\ >=\ 1 || _XOPEN_SOURCE || _POSIX_SOURCE | |
a383b70f MK |
68 | |
69 | .IR siginfo_t : | |
70 | _POSIX_C_SOURCE >= 199309L | |
0f200f07 | 71 | .ad b |
fea681da MK |
72 | .SH DESCRIPTION |
73 | The | |
b7769f32 | 74 | .BR sigaction () |
fea681da MK |
75 | system call is used to change the action taken by a process on |
76 | receipt of a specific signal. | |
f7d174ea MK |
77 | (See |
78 | .BR signal (7) | |
79 | for an overview of signals.) | |
fea681da MK |
80 | .PP |
81 | .I signum | |
82 | specifies the signal and can be any valid signal except | |
83 | .B SIGKILL | |
84 | and | |
85 | .BR SIGSTOP . | |
86 | .PP | |
87 | If | |
88 | .I act | |
f38d8f71 | 89 | is non-NULL, the new action for signal |
fea681da MK |
90 | .I signum |
91 | is installed from | |
92 | .IR act . | |
93 | If | |
94 | .I oldact | |
f38d8f71 | 95 | is non-NULL, the previous action is saved in |
fea681da MK |
96 | .IR oldact . |
97 | .PP | |
98 | The | |
b7769f32 | 99 | .I sigaction |
c810983b | 100 | structure is defined as something like: |
fea681da | 101 | .sp |
bd191423 | 102 | .in +4n |
fea681da MK |
103 | .nf |
104 | struct sigaction { | |
521bf584 MK |
105 | void (*sa_handler)(int); |
106 | void (*sa_sigaction)(int, siginfo_t *, void *); | |
107 | sigset_t sa_mask; | |
108 | int sa_flags; | |
109 | void (*sa_restorer)(void); | |
ca62583f | 110 | }; |
fea681da | 111 | .fi |
bd191423 | 112 | .in |
fea681da | 113 | .PP |
e9496f74 | 114 | On some architectures a union is involved: do not assign to both |
fea681da MK |
115 | .I sa_handler |
116 | and | |
117 | .IR sa_sigaction . | |
118 | .PP | |
119 | The | |
120 | .I sa_restorer | |
48c281d7 MK |
121 | field is not intended for application use. |
122 | (POSIX does not specify a | |
fea681da | 123 | .I sa_restorer |
6e57d26c | 124 | field.) |
48c281d7 MK |
125 | Some further details of purpose of this field can be found in |
126 | .BR sigreturn (2). | |
fea681da MK |
127 | .PP |
128 | .I sa_handler | |
129 | specifies the action to be associated with | |
130 | .I signum | |
131 | and may be | |
132 | .B SIG_DFL | |
c13182ef | 133 | for the default action, |
fea681da MK |
134 | .B SIG_IGN |
135 | to ignore this signal, or a pointer to a signal handling function. | |
136 | This function receives the signal number as its only argument. | |
137 | .PP | |
00161f1b MK |
138 | If |
139 | .B SA_SIGINFO | |
140 | is specified in | |
c13182ef | 141 | .IR sa_flags , |
00161f1b | 142 | then |
fea681da | 143 | .I sa_sigaction |
00161f1b MK |
144 | (instead of |
145 | .IR sa_handler ) | |
146 | specifies the signal-handling function for | |
fea681da MK |
147 | .IR signum . |
148 | This function receives the signal number as its first argument, a | |
149 | pointer to a | |
150 | .I siginfo_t | |
151 | as its second argument and a pointer to a | |
152 | .I ucontext_t | |
c810983b | 153 | (cast to \fIvoid\ *\fP) as its third argument. |
0048657d MK |
154 | (Commonly, the handler function doesn't make any use of the third argument. |
155 | See | |
fb872845 | 156 | .BR getcontext (3) |
0048657d MK |
157 | for further information about |
158 | .IR ucontext_t .) | |
fea681da MK |
159 | .PP |
160 | .I sa_mask | |
7acf5ebe MK |
161 | specifies a mask of signals which should be blocked |
162 | (i.e., added to the signal mask of the thread in which | |
163 | the signal handler is invoked) | |
164 | during execution of the signal handler. | |
c13182ef | 165 | In addition, the signal which triggered the handler |
fea681da MK |
166 | will be blocked, unless the |
167 | .B SA_NODEFER | |
b7769f32 | 168 | flag is used. |
fea681da MK |
169 | .PP |
170 | .I sa_flags | |
bbd7e60a | 171 | specifies a set of flags which modify the behavior of the signal. |
c13182ef | 172 | It is formed by the bitwise OR of zero or more of the following: |
bd191423 | 173 | .RS 4 |
fea681da MK |
174 | .TP |
175 | .B SA_NOCLDSTOP | |
176 | If | |
177 | .I signum | |
178 | is | |
1cbdceb1 MK |
179 | .BR SIGCHLD , |
180 | do not receive notification when child processes stop (i.e., when they | |
181 | receive one of | |
12ccb8fc | 182 | .BR SIGSTOP ", " SIGTSTP ", " SIGTTIN ", " |
fea681da | 183 | or |
1cbdceb1 MK |
184 | .BR SIGTTOU ) |
185 | or resume (i.e., they receive | |
186 | .BR SIGCONT ) | |
187 | (see | |
188 | .BR wait (2)). | |
33a0ccb2 | 189 | This flag is meaningful only when establishing a handler for |
bbd7e60a | 190 | .BR SIGCHLD . |
fea681da | 191 | .TP |
665f1e69 | 192 | .BR SA_NOCLDWAIT " (since Linux 2.6)" |
1cbdceb1 MK |
193 | .\" To be precise: Linux 2.5.60 -- MTK |
194 | If | |
195 | .I signum | |
196 | is | |
197 | .BR SIGCHLD , | |
198 | do not transform children into zombies when they terminate. | |
199 | See also | |
b7769f32 | 200 | .BR waitpid (2). |
33a0ccb2 | 201 | This flag is meaningful only when establishing a handler for |
bbd7e60a MK |
202 | .BR SIGCHLD , |
203 | or when setting that signal's disposition to | |
204 | .BR SIG_DFL . | |
205 | ||
206 | If the | |
207 | .B SA_NOCLDWAIT | |
208 | flag is set when establishing a handler for | |
209 | .BR SIGCHLD , | |
210 | POSIX.1 leaves it unspecified whether a | |
211 | .B SIGCHLD | |
212 | signal is generated when a child process terminates. | |
213 | On Linux, a | |
214 | .B SIGCHLD | |
215 | signal is generated in this case; | |
216 | on some other implementations, it is not. | |
1cbdceb1 | 217 | .TP |
c810983b MK |
218 | .B SA_NODEFER |
219 | Do not prevent the signal from being received from within its own signal | |
220 | handler. | |
33a0ccb2 | 221 | This flag is meaningful only when establishing a signal handler. |
c810983b | 222 | .B SA_NOMASK |
c8f2dd47 | 223 | is an obsolete, nonstandard synonym for this flag. |
fea681da | 224 | .TP |
0daa9e92 | 225 | .B SA_ONSTACK |
c13182ef | 226 | Call the signal handler on an alternate signal stack provided by |
fea681da MK |
227 | .BR sigaltstack (2). |
228 | If an alternate stack is not available, the default stack will be used. | |
33a0ccb2 | 229 | This flag is meaningful only when establishing a signal handler. |
fea681da | 230 | .TP |
c810983b | 231 | .BR SA_RESETHAND |
ca15be91 | 232 | Restore the signal action to the default upon entry to the signal handler. |
33a0ccb2 | 233 | This flag is meaningful only when establishing a signal handler. |
c810983b | 234 | .B SA_ONESHOT |
c8f2dd47 | 235 | is an obsolete, nonstandard synonym for this flag. |
c810983b | 236 | .TP |
fea681da | 237 | .B SA_RESTART |
d9bfdb9c | 238 | Provide behavior compatible with BSD signal semantics by making certain |
fea681da | 239 | system calls restartable across signals. |
33a0ccb2 | 240 | This flag is meaningful only when establishing a signal handler. |
bbd7e60a MK |
241 | See |
242 | .BR signal (7) | |
243 | for a discussion of system call restarting. | |
fea681da | 244 | .TP |
24029e9f MK |
245 | .BR SA_RESTORER |
246 | .IR "Not intended for application use" . | |
247 | This flag is used by C libraries to indicate that the | |
248 | .IR sa_restorer | |
249 | field contains the address of a "signal trampoline". | |
250 | See | |
251 | .BR sigreturn (2) | |
252 | for more details. | |
253 | .TP | |
bbd7e60a | 254 | .BR SA_SIGINFO " (since Linux 2.2)" |
a38a23a1 | 255 | The signal handler takes three arguments, not one. |
c13182ef | 256 | In this case, |
fea681da MK |
257 | .I sa_sigaction |
258 | should be set instead of | |
259 | .IR sa_handler . | |
33a0ccb2 | 260 | This flag is meaningful only when establishing a signal handler. |
bbd7e60a MK |
261 | .\" (The |
262 | .\" .I sa_sigaction | |
263 | .\" field was added in Linux 2.1.86.) | |
fea681da MK |
264 | .RE |
265 | .PP | |
266 | The | |
267 | .I siginfo_t | |
c4bb193f | 268 | argument to |
fea681da | 269 | .I sa_sigaction |
a8e85174 | 270 | is a struct with the following fields: |
fea681da | 271 | .sp |
bd191423 | 272 | .in +4n |
fea681da | 273 | .nf |
fea681da | 274 | siginfo_t { |
bcd0ba54 MK |
275 | int si_signo; /* Signal number */ |
276 | int si_errno; /* An errno value */ | |
277 | int si_code; /* Signal code */ | |
278 | int si_trapno; /* Trap number that caused | |
279 | hardware-generated signal | |
280 | (unused on most architectures) */ | |
c810983b | 281 | .\" FIXME |
11c40dbd | 282 | .\" The siginfo_t 'si_trapno' field seems to be used only on SPARC and Alpha; |
c810983b | 283 | .\" this page could use a little more detail on its purpose there. |
bcd0ba54 MK |
284 | pid_t si_pid; /* Sending process ID */ |
285 | uid_t si_uid; /* Real user ID of sending process */ | |
286 | int si_status; /* Exit value or signal */ | |
287 | clock_t si_utime; /* User time consumed */ | |
288 | clock_t si_stime; /* System time consumed */ | |
289 | sigval_t si_value; /* Signal value */ | |
290 | int si_int; /* POSIX.1b signal */ | |
291 | void *si_ptr; /* POSIX.1b signal */ | |
292 | int si_overrun; /* Timer overrun count; | |
293 | POSIX.1b timers */ | |
294 | int si_timerid; /* Timer ID; POSIX.1b timers */ | |
c810983b | 295 | .\" In the kernel: si_tid |
bcd0ba54 MK |
296 | void *si_addr; /* Memory location which caused fault */ |
297 | long si_band; /* Band event (was \fIint\fP in | |
298 | glibc 2.3.2 and earlier) */ | |
299 | int si_fd; /* File descriptor */ | |
300 | short si_addr_lsb; /* Least significant bit of address | |
301 | (since Linux 2.6.32) */ | |
302 | void *si_call_addr; /* Address of system call instruction | |
303 | (since Linux 3.5) */ | |
304 | int si_syscall; /* Number of attempted system call | |
305 | (since Linux 3.5) */ | |
306 | unsigned int si_arch; /* Architecture of attempted system call | |
307 | (since Linux 3.5) */ | |
fea681da MK |
308 | } |
309 | .fi | |
bd191423 | 310 | .in |
fea681da MK |
311 | |
312 | .IR si_signo ", " si_errno " and " si_code | |
313 | are defined for all signals. | |
73932e12 | 314 | .RI ( si_errno |
c810983b | 315 | is generally unused on Linux.) |
33a0ccb2 MK |
316 | The rest of the struct may be a union, so that one should |
317 | read only the fields that are meaningful for the given signal: | |
2e519bf2 | 318 | .IP * 2 |
665f1e69 MK |
319 | Signals sent with |
320 | .BR kill (2) | |
321 | and | |
485ab701 | 322 | .BR sigqueue (3) |
b7769f32 | 323 | fill in |
fea681da | 324 | .IR si_pid " and " si_uid . |
4176590c | 325 | In addition, signals sent with |
485ab701 | 326 | .BR sigqueue (3) |
4176590c MK |
327 | fill in |
328 | .IR si_int " and " si_ptr | |
53d30e45 | 329 | with the values specified by the sender of the signal; |
4176590c | 330 | see |
485ab701 | 331 | .BR sigqueue (3) |
4176590c | 332 | for more details. |
2e519bf2 | 333 | .IP * |
80752fa5 | 334 | Signals sent by POSIX.1b timers (since Linux 2.6) fill in |
c810983b MK |
335 | .I si_overrun |
336 | and | |
337 | .IR si_timerid . | |
338 | The | |
339 | .I si_timerid | |
340 | field is an internal ID used by the kernel to identify | |
341 | the timer; it is not the same as the timer ID returned by | |
804f03e6 | 342 | .BR timer_create (2). |
665f1e69 MK |
343 | The |
344 | .I si_overrun | |
345 | field is the timer overrun count; | |
346 | this is the same information as is obtained by a call to | |
347 | .BR timer_getoverrun (2). | |
348 | These fields are nonstandard Linux extensions. | |
c810983b | 349 | .IP * |
5ffadafd MK |
350 | Signals sent for message queue notification (see the description of |
351 | .B SIGEV_SIGNAL | |
352 | in | |
353 | .BR mq_notify (3)) | |
354 | fill in | |
355 | .IR si_int / si_ptr , | |
356 | with the | |
357 | .I sigev_value | |
358 | supplied to | |
359 | .BR mq_notify (3); | |
360 | .IR si_pid , | |
361 | with the process ID of the message sender; and | |
362 | .IR si_uid , | |
363 | with the real user ID of the message sender. | |
364 | .IP * | |
b7769f32 | 365 | .B SIGCHLD |
c810983b | 366 | fills in |
a797afac | 367 | .IR si_pid ", " si_uid ", " si_status ", " si_utime ", and " si_stime , |
665f1e69 MK |
368 | providing information about the child. |
369 | The | |
370 | .I si_pid | |
371 | field is the process ID of the child; | |
372 | .I si_uid | |
373 | is the child's real user ID. | |
374 | The | |
375 | .I si_status | |
376 | field contains the exit status of the child (if | |
377 | .I si_code | |
378 | is | |
379 | .BR CLD_EXITED ), | |
380 | or the signal number that caused the process to change state. | |
45f2d4eb MK |
381 | The |
382 | .I si_utime | |
383 | and | |
384 | .I si_stime | |
665f1e69 MK |
385 | contain the user and system CPU time used by the child process; |
386 | these fields do not include the times used by waited-for children (unlike | |
45f2d4eb MK |
387 | .BR getrusage (2) |
388 | and | |
7dd874ef | 389 | .BR times (2)). |
45f2d4eb MK |
390 | In kernels up to 2.6, and since 2.6.27, these fields report |
391 | CPU time in units of | |
392 | .IR sysconf(_SC_CLK_TCK) . | |
393 | In 2.6 kernels before 2.6.27, | |
394 | a bug meant that these fields reported time in units | |
395 | of the (configurable) system jiffy (see | |
396 | .BR time (7)). | |
665f1e69 | 397 | .\" FIXME . |
d03d9a05 MK |
398 | .\" When si_utime and si_stime where originally implemented, the |
399 | .\" measurement unit was HZ, which was the same as clock ticks | |
400 | .\" (sysconf(_SC_CLK_TCK)). In 2.6, HZ became configurable, and | |
401 | .\" was *still* used as the unit to return the info these fields, | |
402 | .\" with the result that the field values depended on the the | |
403 | .\" configured HZ. Of course, the should have been measured in | |
00ac6ce4 | 404 | .\" USER_HZ instead, so that sysconf(_SC_CLK_TCK) could be used to |
d03d9a05 MK |
405 | .\" convert to seconds. I have a queued patch to fix this: |
406 | .\" http://thread.gmane.org/gmane.linux.kernel/698061/ . | |
45f2d4eb | 407 | .\" This patch made it into 2.6.27. |
d03d9a05 | 408 | .\" But note that these fields still don't return the times of |
17b78786 | 409 | .\" waited-for children (as is done by getrusage() and times() |
d03d9a05 | 410 | .\" and wait4()). Solaris 8 does include child times. |
2e519bf2 | 411 | .IP * |
c13182ef | 412 | .BR SIGILL , |
b7769f32 | 413 | .BR SIGFPE , |
c13182ef | 414 | .BR SIGSEGV , |
c2261e74 | 415 | .BR SIGBUS , |
b7769f32 | 416 | and |
c2261e74 | 417 | .BR SIGTRAP |
b7769f32 | 418 | fill in |
fea681da MK |
419 | .I si_addr |
420 | with the address of the fault. | |
c2261e74 MK |
421 | On some architectures, |
422 | these signals also fill in the | |
423 | .I si_trapno | |
7d082bab | 424 | field. |
f402032c | 425 | Some suberrors of |
665f1e69 | 426 | .BR SIGBUS , |
f402032c AK |
427 | in particular |
428 | .B BUS_MCEERR_AO | |
429 | and | |
430 | .BR BUS_MCEERR_AR , | |
431 | also fill in | |
432 | .IR si_addr_lsb . | |
433 | This field indicates the least significant bit of the reported address | |
434 | and therefore the extent of the corruption. | |
435 | For example, if a full page was corrupted, | |
436 | .I si_addr_lsb | |
b911dcb0 | 437 | contains |
f402032c | 438 | .IR log2(sysconf(_SC_PAGESIZE)) . |
3b4a59c4 KC |
439 | When |
440 | .BR SIGTRAP | |
441 | is delivered in response to a | |
442 | .BR ptrace (2) | |
443 | event (PTRACE_EVENT_foo), | |
444 | .I si_addr | |
445 | is not populated, but | |
446 | .I si_pid | |
447 | and | |
448 | .I si_uid | |
449 | are populated with the respective process ID and user ID responsible for | |
e1954b03 MK |
450 | delivering the trap. |
451 | In the case of | |
c937b973 | 452 | .BR seccomp (2), |
3b4a59c4 | 453 | the tracee will be shown as delivering the event. |
a1d88c4c | 454 | .B BUS_MCEERR_* |
f402032c AK |
455 | and |
456 | .I si_addr_lsb | |
457 | are Linux-specific extensions. | |
665f1e69 | 458 | .IP * |
dff6bb19 MK |
459 | .BR SIGIO / SIGPOLL |
460 | (the two names are synonyms on Linux) | |
b7769f32 | 461 | fills in |
fea681da | 462 | .IR si_band " and " si_fd . |
665f1e69 MK |
463 | The |
464 | .I si_band | |
465 | event is a bit mask containing the same values as are filled in the | |
466 | .I revents | |
467 | field by | |
468 | .BR poll (2). | |
469 | The | |
470 | .I si_fd | |
b1f91dc1 MK |
471 | field indicates the file descriptor for which the I/O event occurred; |
472 | for further details, see the description of | |
5ffdc2fd | 473 | .BR F_SETSIG |
b1f91dc1 MK |
474 | in |
475 | .BR fcntl (2). | |
bcd0ba54 | 476 | .IP * |
a1d88c4c | 477 | .BR SIGSYS , |
b11bccf8 | 478 | generated (since Linux 3.5) |
bcd0ba54 | 479 | .\" commit a0727e8ce513fe6890416da960181ceb10fbfae6 |
b11bccf8 MK |
480 | when a seccomp filter returns |
481 | .BR SECCOMP_RET_TRAP , | |
bcd0ba54 MK |
482 | fills in |
483 | .IR si_call_addr , | |
484 | .IR si_syscall , | |
485 | .IR si_arch , | |
3b4a59c4 KC |
486 | .IR si_errno , |
487 | and other fields as described in | |
bcd0ba54 | 488 | .BR seccomp (2). |
2e519bf2 | 489 | .PP |
fea681da | 490 | .I si_code |
e1954b03 MK |
491 | is a value (not a bit mask) indicating why this signal was sent. |
492 | For a | |
3b4a59c4 KC |
493 | .BR ptrace (2) |
494 | event, | |
495 | .I si_code | |
496 | will contain | |
497 | .BR SIGTRAP | |
498 | and have the ptrace event in the high byte: | |
499 | ||
500 | .nf | |
501 | (SIGTRAP | PTRACE_EVENT_foo << 8). | |
502 | .fi | |
503 | ||
504 | For a regular signal, the following list shows the values which can be | |
505 | placed in | |
1812a949 MK |
506 | .I si_code |
507 | for any signal, along with reason that the signal was generated. | |
508 | .RS 4 | |
d443e2fa | 509 | .TP |
1812a949 | 510 | .B SI_USER |
ff953a8d | 511 | .BR kill (2). |
1812a949 MK |
512 | .TP |
513 | .B SI_KERNEL | |
514 | Sent by the kernel. | |
515 | .TP | |
516 | .B SI_QUEUE | |
ff953a8d | 517 | .BR sigqueue (3). |
1812a949 MK |
518 | .TP |
519 | .B SI_TIMER | |
ff953a8d | 520 | POSIX timer expired. |
1812a949 | 521 | .TP |
eb83484f MK |
522 | .BR SI_MESGQ " (since Linux 2.6.6)" |
523 | POSIX message queue state changed; see | |
ff953a8d | 524 | .BR mq_notify (3). |
1812a949 MK |
525 | .TP |
526 | .B SI_ASYNCIO | |
ff953a8d | 527 | AIO completed. |
1812a949 MK |
528 | .TP |
529 | .B SI_SIGIO | |
dff6bb19 MK |
530 | Queued |
531 | .B SIGIO | |
532 | (only in kernels up to Linux 2.2; from Linux 2.4 onward | |
533 | .BR SIGIO / SIGPOLL | |
534 | fills in | |
535 | .I si_code | |
536 | as described below). | |
1812a949 | 537 | .TP |
eb83484f | 538 | .BR SI_TKILL " (since Linux 2.4.19)" |
1812a949 MK |
539 | .BR tkill (2) |
540 | or | |
ff953a8d | 541 | .BR tgkill (2). |
92057f4d | 542 | .\" SI_DETHREAD is defined in 2.6.9 sources, but isn't implemented |
c13182ef | 543 | .\" It appears to have been an idea that was tried during 2.5.6 |
92057f4d | 544 | .\" through to 2.5.24 and then was backed out. |
1812a949 MK |
545 | .RE |
546 | .PP | |
6beb1671 | 547 | The following values can be placed in |
1812a949 MK |
548 | .I si_code |
549 | for a | |
550 | .B SIGILL | |
551 | signal: | |
552 | .RS 4 | |
d443e2fa | 553 | .TP |
1812a949 | 554 | .B ILL_ILLOPC |
ff953a8d | 555 | Illegal opcode. |
1812a949 MK |
556 | .TP |
557 | .B ILL_ILLOPN | |
ff953a8d | 558 | Illegal operand. |
1812a949 MK |
559 | .TP |
560 | .B ILL_ILLADR | |
ff953a8d | 561 | Illegal addressing mode. |
1812a949 MK |
562 | .TP |
563 | .B ILL_ILLTRP | |
ff953a8d | 564 | Illegal trap. |
1812a949 MK |
565 | .TP |
566 | .B ILL_PRVOPC | |
ff953a8d | 567 | Privileged opcode. |
1812a949 MK |
568 | .TP |
569 | .B ILL_PRVREG | |
ff953a8d | 570 | Privileged register. |
1812a949 MK |
571 | .TP |
572 | .B ILL_COPROC | |
ff953a8d | 573 | Coprocessor error. |
1812a949 MK |
574 | .TP |
575 | .B ILL_BADSTK | |
ff953a8d | 576 | Internal stack error. |
1812a949 MK |
577 | .RE |
578 | .PP | |
6beb1671 | 579 | The following values can be placed in |
1812a949 MK |
580 | .I si_code |
581 | for a | |
582 | .B SIGFPE | |
583 | signal: | |
584 | .RS 4 | |
d443e2fa | 585 | .TP |
1812a949 | 586 | .B FPE_INTDIV |
ff953a8d | 587 | Integer divide by zero. |
1812a949 MK |
588 | .TP |
589 | .B FPE_INTOVF | |
ff953a8d | 590 | Integer overflow. |
1812a949 MK |
591 | .TP |
592 | .B FPE_FLTDIV | |
ff953a8d | 593 | Floating-point divide by zero. |
1812a949 MK |
594 | .TP |
595 | .B FPE_FLTOVF | |
ff953a8d | 596 | Floating-point overflow. |
1812a949 MK |
597 | .TP |
598 | .B FPE_FLTUND | |
ff953a8d | 599 | Floating-point underflow. |
1812a949 MK |
600 | .TP |
601 | .B FPE_FLTRES | |
ff953a8d | 602 | Floating-point inexact result. |
1812a949 MK |
603 | .TP |
604 | .B FPE_FLTINV | |
ff953a8d | 605 | Floating-point invalid operation. |
1812a949 MK |
606 | .TP |
607 | .B FPE_FLTSUB | |
ff953a8d | 608 | Subscript out of range. |
1812a949 MK |
609 | .RE |
610 | .PP | |
6beb1671 | 611 | The following values can be placed in |
1812a949 MK |
612 | .I si_code |
613 | for a | |
614 | .B SIGSEGV | |
615 | signal: | |
616 | .RS 4 | |
d443e2fa | 617 | .TP |
1812a949 | 618 | .B SEGV_MAPERR |
ff953a8d | 619 | Address not mapped to object. |
1812a949 MK |
620 | .TP |
621 | .B SEGV_ACCERR | |
ff953a8d | 622 | Invalid permissions for mapped object. |
1812a949 MK |
623 | .RE |
624 | .PP | |
6beb1671 | 625 | The following values can be placed in |
1812a949 MK |
626 | .I si_code |
627 | for a | |
628 | .B SIGBUS | |
629 | signal: | |
630 | .RS 4 | |
d443e2fa | 631 | .TP |
1812a949 | 632 | .B BUS_ADRALN |
ff953a8d | 633 | Invalid address alignment. |
1812a949 MK |
634 | .TP |
635 | .B BUS_ADRERR | |
ff953a8d | 636 | Nonexistent physical address. |
1812a949 MK |
637 | .TP |
638 | .B BUS_OBJERR | |
ff953a8d | 639 | Object-specific hardware error. |
f402032c AK |
640 | .TP |
641 | .BR BUS_MCEERR_AR " (since Linux 2.6.32)" | |
642 | Hardware memory error consumed on a machine check; action required. | |
643 | .TP | |
644 | .BR BUS_MCEERR_AO " (since Linux 2.6.32)" | |
645 | Hardware memory error detected in process but not consumed; action optional. | |
1812a949 MK |
646 | .RE |
647 | .PP | |
6beb1671 | 648 | The following values can be placed in |
1812a949 MK |
649 | .I si_code |
650 | for a | |
651 | .B SIGTRAP | |
652 | signal: | |
653 | .RS 4 | |
d443e2fa | 654 | .TP |
1812a949 | 655 | .B TRAP_BRKPT |
ff953a8d | 656 | Process breakpoint. |
1812a949 MK |
657 | .TP |
658 | .B TRAP_TRACE | |
ff953a8d | 659 | Process trace trap. |
39efed93 MK |
660 | .TP |
661 | .BR TRAP_BRANCH " (since Linux 2.4)" | |
ff953a8d | 662 | Process taken branch trap. |
39efed93 MK |
663 | .TP |
664 | .BR TRAP_HWBKPT " (since Linux 2.4)" | |
ff953a8d | 665 | Hardware breakpoint/watchpoint. |
1812a949 MK |
666 | .RE |
667 | .PP | |
6beb1671 | 668 | The following values can be placed in |
1812a949 MK |
669 | .I si_code |
670 | for a | |
688e23c6 | 671 | .B SIGCHLD |
1812a949 MK |
672 | signal: |
673 | .RS 4 | |
d443e2fa | 674 | .TP |
1812a949 | 675 | .B CLD_EXITED |
ff953a8d | 676 | Child has exited. |
1812a949 MK |
677 | .TP |
678 | .B CLD_KILLED | |
ff953a8d | 679 | Child was killed. |
1812a949 MK |
680 | .TP |
681 | .B CLD_DUMPED | |
ff953a8d | 682 | Child terminated abnormally. |
1812a949 MK |
683 | .TP |
684 | .B CLD_TRAPPED | |
ff953a8d | 685 | Traced child has trapped. |
1812a949 MK |
686 | .TP |
687 | .B CLD_STOPPED | |
ff953a8d | 688 | Child has stopped. |
1812a949 | 689 | .TP |
eb83484f | 690 | .BR CLD_CONTINUED " (since Linux 2.6.9)" |
ff953a8d | 691 | Stopped child has continued. |
1812a949 MK |
692 | .RE |
693 | .PP | |
6beb1671 | 694 | The following values can be placed in |
1812a949 MK |
695 | .I si_code |
696 | for a | |
dff6bb19 | 697 | .BR SIGIO / SIGPOLL |
1812a949 MK |
698 | signal: |
699 | .RS 4 | |
d443e2fa | 700 | .TP |
1812a949 | 701 | .B POLL_IN |
ff953a8d | 702 | Data input available. |
1812a949 MK |
703 | .TP |
704 | .B POLL_OUT | |
ff953a8d | 705 | Output buffers available. |
1812a949 MK |
706 | .TP |
707 | .B POLL_MSG | |
ff953a8d | 708 | Input message available. |
1812a949 MK |
709 | .TP |
710 | .B POLL_ERR | |
ff953a8d | 711 | I/O error. |
1812a949 MK |
712 | .TP |
713 | .B POLL_PRI | |
ff953a8d | 714 | High priority input available. |
1812a949 MK |
715 | .TP |
716 | .B POLL_HUP | |
ff953a8d | 717 | Device disconnected. |
1812a949 | 718 | .RE |
3b4a59c4 KC |
719 | .PP |
720 | The following value can be placed in | |
721 | .I si_code | |
722 | for a | |
723 | .BR SIGSYS | |
724 | signal: | |
725 | .RS 4 | |
d443e2fa | 726 | .TP |
3b4a59c4 | 727 | .BR SYS_SECCOMP " (since Linux 3.5)" |
ff953a8d | 728 | Triggered by a |
3b4a59c4 | 729 | .BR seccomp (2) |
ff953a8d | 730 | filter rule. |
3b4a59c4 | 731 | .RE |
47297adb | 732 | .SH RETURN VALUE |
00161f1b | 733 | .BR sigaction () |
de86e93c MK |
734 | returns 0 on success; on error, \-1 is returned, and |
735 | .I errno | |
736 | is set to indicate the error. | |
fea681da MK |
737 | .SH ERRORS |
738 | .TP | |
739 | .B EFAULT | |
00161f1b MK |
740 | .IR act " or " oldact |
741 | points to memory which is not a valid part of the process address space. | |
fea681da MK |
742 | .TP |
743 | .B EINVAL | |
c13182ef MK |
744 | An invalid signal was specified. |
745 | This will also be generated if an attempt | |
fea681da MK |
746 | is made to change the action for |
747 | .BR SIGKILL " or " SIGSTOP ", " | |
00161f1b | 748 | which cannot be caught or ignored. |
47297adb | 749 | .SH CONFORMING TO |
ab8cd127 | 750 | POSIX.1-2001, POSIX.1-2008, SVr4. |
2dd578fd | 751 | .\" SVr4 does not document the EINTR condition. |
fea681da | 752 | .SH NOTES |
3fb46b2b | 753 | A child created via |
0ac0def4 MK |
754 | .BR fork (2) |
755 | inherits a copy of its parent's signal dispositions. | |
756 | During an | |
757 | .BR execve (2), | |
758 | the dispositions of handled signals are reset to the default; | |
759 | the dispositions of ignored signals are left unchanged. | |
760 | ||
d9bfdb9c | 761 | According to POSIX, the behavior of a process is undefined after it |
b7769f32 MK |
762 | ignores a |
763 | .BR SIGFPE , | |
764 | .BR SIGILL , | |
765 | or | |
0daa9e92 | 766 | .B SIGSEGV |
b7769f32 | 767 | signal that was not generated by |
0bfa087b | 768 | .BR kill (2) |
b7769f32 | 769 | or |
0bfa087b | 770 | .BR raise (3). |
fea681da | 771 | Integer division by zero has undefined result. |
b7769f32 MK |
772 | On some architectures it will generate a |
773 | .B SIGFPE | |
774 | signal. | |
8bd58774 MK |
775 | (Also dividing the most negative integer by \-1 may generate |
776 | .BR SIGFPE .) | |
fea681da MK |
777 | Ignoring this signal might lead to an endless loop. |
778 | .PP | |
b7769f32 MK |
779 | POSIX.1-1990 disallowed setting the action for |
780 | .B SIGCHLD | |
781 | to | |
782 | .BR SIG_IGN . | |
ab8cd127 | 783 | POSIX.1-2001 and later allow this possibility, so that ignoring |
b7769f32 MK |
784 | .B SIGCHLD |
785 | can be used to prevent the creation of zombies (see | |
786 | .BR wait (2)). | |
efbfd7ec | 787 | Nevertheless, the historical BSD and System\ V behaviors for ignoring |
b7769f32 MK |
788 | .B SIGCHLD |
789 | differ, so that the only completely portable method of ensuring that | |
790 | terminated children do not become zombies is to catch the | |
791 | .B SIGCHLD | |
792 | signal and perform a | |
793 | .BR wait (2) | |
794 | or similar. | |
fea681da | 795 | .PP |
33a0ccb2 | 796 | POSIX.1-1990 specified only |
fea681da | 797 | .BR SA_NOCLDSTOP . |
b7769f32 | 798 | POSIX.1-2001 added |
e6a773f6 | 799 | .BR SA_NOCLDSTOP , |
b7769f32 | 800 | .BR SA_NOCLDWAIT , |
b7769f32 | 801 | .BR SA_NODEFER , |
e6a773f6 MK |
802 | .BR SA_ONSTACK , |
803 | .BR SA_RESETHAND , | |
804 | .BR SA_RESTART , | |
b7769f32 MK |
805 | and |
806 | .BR SA_SIGINFO . | |
807 | Use of these latter values in | |
fea681da | 808 | .I sa_flags |
b7769f32 | 809 | may be less portable in applications intended for older |
008f1ecc | 810 | UNIX implementations. |
b7769f32 | 811 | .PP |
fea681da MK |
812 | The |
813 | .B SA_RESETHAND | |
814 | flag is compatible with the SVr4 flag of the same name. | |
815 | .PP | |
816 | The | |
817 | .B SA_NODEFER | |
818 | flag is compatible with the SVr4 flag of the same name under kernels | |
c13182ef MK |
819 | 1.3.9 and newer. |
820 | On older kernels the Linux implementation | |
fea681da MK |
821 | allowed the receipt of any signal, not just the one we are installing |
822 | (effectively overriding any | |
823 | .I sa_mask | |
824 | settings). | |
fea681da | 825 | .PP |
b7769f32 | 826 | .BR sigaction () |
460b3d61 | 827 | can be called with a NULL second argument to query the current signal |
c13182ef MK |
828 | handler. |
829 | It can also be used to check whether a given signal is valid for | |
460b3d61 | 830 | the current machine by calling it with NULL second and third arguments. |
fea681da | 831 | .PP |
c13182ef | 832 | It is not possible to block |
00161f1b MK |
833 | .BR SIGKILL " or " SIGSTOP |
834 | (by specifying them in | |
835 | .IR sa_mask ). | |
836 | Attempts to do so are silently ignored. | |
837 | .PP | |
fea681da MK |
838 | See |
839 | .BR sigsetops (3) | |
840 | for details on manipulating signal sets. | |
2e519bf2 MK |
841 | .PP |
842 | See | |
843 | .BR signal (7) | |
988db661 | 844 | for a list of the async-signal-safe functions that can be |
2e519bf2 | 845 | safely called inside from inside a signal handler. |
1545ed95 | 846 | .\" |
0722a578 | 847 | .SS C library/kernel differences |
ee053db8 MK |
848 | The glibc wrapper function for |
849 | .BR sigaction () | |
850 | gives an error | |
851 | .RB ( EINVAL ) | |
852 | on attempts to change the disposition of the two real-time signals | |
853 | used internally by the NPTL threading implementation. | |
854 | See | |
855 | .BR nptl (7) | |
856 | for details. | |
857 | ||
1545ed95 MK |
858 | The original Linux system call was named |
859 | .BR sigaction (). | |
860 | However, with the addition of real-time signals in Linux 2.2, | |
861 | the fixed-size, 32-bit | |
862 | .IR sigset_t | |
863 | type supported by that system call was no longer fit for purpose. | |
864 | Consequently, a new system call, | |
865 | .BR rt_sigaction (), | |
866 | was added to support an enlarged | |
867 | .IR sigset_t | |
868 | type. | |
869 | The new system call takes a fourth argument, | |
870 | .IR "size_t sigsetsize" , | |
871 | which specifies the size in bytes of the signal sets in | |
872 | .IR act.sa_mask | |
873 | and | |
874 | .IR oldact.sa_mask . | |
875 | This argument is currently required to have the value | |
876 | .IR sizeof(sigset_t) | |
877 | (or the error | |
878 | .B EINVAL | |
879 | results). | |
880 | The glibc | |
881 | .BR sigaction () | |
882 | wrapper function hides these details from us, transparently calling | |
883 | .BR rt_sigaction () | |
884 | when the kernel provides it. | |
885 | .\" | |
4a19cb8c MK |
886 | .SS Undocumented |
887 | Before the introduction of | |
d231b918 | 888 | .BR SA_SIGINFO , |
4a19cb8c MK |
889 | it was also possible to get some additional information, |
890 | namely by using a | |
891 | .I sa_handler | |
892 | with second argument of type | |
893 | .IR "struct sigcontext". | |
66a9882e | 894 | See the relevant Linux kernel sources for details. |
4a19cb8c | 895 | This use is obsolete now. |
00161f1b MK |
896 | .SH BUGS |
897 | In kernels up to and including 2.6.13, specifying | |
898 | .B SA_NODEFER | |
899 | in | |
900 | .I sa_flags | |
437a9182 | 901 | prevents not only the delivered signal from being masked during |
00161f1b MK |
902 | execution of the handler, but also the signals specified in |
903 | .IR sa_mask . | |
0643ee28 | 904 | This bug was fixed in kernel 2.6.14. |
af5267b2 MK |
905 | .SH EXAMPLE |
906 | See | |
907 | .BR mprotect (2). | |
47297adb | 908 | .SH SEE ALSO |
fea681da MK |
909 | .BR kill (1), |
910 | .BR kill (2), | |
292d25b0 | 911 | .BR killpg (2), |
fea681da | 912 | .BR pause (2), |
d806bc05 | 913 | .BR restart_syscall (2), |
3b4a59c4 | 914 | .BR seccomp (2) |
fea681da MK |
915 | .BR sigaltstack (2), |
916 | .BR signal (2), | |
058c1165 | 917 | .BR signalfd (2), |
00161f1b | 918 | .BR sigpending (2), |
b71aac7e | 919 | .BR sigreturn (2), |
00161f1b | 920 | .BR sigprocmask (2), |
00161f1b | 921 | .BR sigsuspend (2), |
b7769f32 | 922 | .BR wait (2), |
fea681da MK |
923 | .BR raise (3), |
924 | .BR siginterrupt (3), | |
485ab701 | 925 | .BR sigqueue (3), |
fea681da | 926 | .BR sigsetops (3), |
30ecea55 | 927 | .BR sigvec (3), |
e1a9bc1b | 928 | .BR core (5), |
fea681da | 929 | .BR signal (7) |