]>
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 | .\" |
b8efb414 | 49 | .TH SIGACTION 2 2016-10-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 (): | |
cff459de | 67 | _POSIX_C_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 |
6756ea36 MK |
282 | .\" The siginfo_t 'si_trapno' field seems to be used |
283 | .\" only on SPARC and Alpha; this page could use | |
284 | .\" a little more detail on its purpose there. | |
bcd0ba54 MK |
285 | pid_t si_pid; /* Sending process ID */ |
286 | uid_t si_uid; /* Real user ID of sending process */ | |
287 | int si_status; /* Exit value or signal */ | |
288 | clock_t si_utime; /* User time consumed */ | |
289 | clock_t si_stime; /* System time consumed */ | |
290 | sigval_t si_value; /* Signal value */ | |
291 | int si_int; /* POSIX.1b signal */ | |
292 | void *si_ptr; /* POSIX.1b signal */ | |
293 | int si_overrun; /* Timer overrun count; | |
294 | POSIX.1b timers */ | |
295 | int si_timerid; /* Timer ID; POSIX.1b timers */ | |
c810983b | 296 | .\" In the kernel: si_tid |
bcd0ba54 MK |
297 | void *si_addr; /* Memory location which caused fault */ |
298 | long si_band; /* Band event (was \fIint\fP in | |
299 | glibc 2.3.2 and earlier) */ | |
300 | int si_fd; /* File descriptor */ | |
301 | short si_addr_lsb; /* Least significant bit of address | |
302 | (since Linux 2.6.32) */ | |
0c962aab MK |
303 | void *si_lower; /* Lower bound when address violation |
304 | occurred (since Linux 3.19) */ | |
305 | void *si_upper; /* Upper bound when address violation | |
306 | occurred (since Linux 3.19) */ | |
9f6007b8 MK |
307 | int si_pkey; /* Protection key on PTE that caused |
308 | fault (since Linux 4.6) */ | |
bcd0ba54 MK |
309 | void *si_call_addr; /* Address of system call instruction |
310 | (since Linux 3.5) */ | |
311 | int si_syscall; /* Number of attempted system call | |
312 | (since Linux 3.5) */ | |
313 | unsigned int si_arch; /* Architecture of attempted system call | |
314 | (since Linux 3.5) */ | |
fea681da MK |
315 | } |
316 | .fi | |
bd191423 | 317 | .in |
fea681da MK |
318 | |
319 | .IR si_signo ", " si_errno " and " si_code | |
320 | are defined for all signals. | |
73932e12 | 321 | .RI ( si_errno |
c810983b | 322 | is generally unused on Linux.) |
33a0ccb2 MK |
323 | The rest of the struct may be a union, so that one should |
324 | read only the fields that are meaningful for the given signal: | |
2e519bf2 | 325 | .IP * 2 |
665f1e69 MK |
326 | Signals sent with |
327 | .BR kill (2) | |
328 | and | |
485ab701 | 329 | .BR sigqueue (3) |
b7769f32 | 330 | fill in |
fea681da | 331 | .IR si_pid " and " si_uid . |
4176590c | 332 | In addition, signals sent with |
485ab701 | 333 | .BR sigqueue (3) |
4176590c MK |
334 | fill in |
335 | .IR si_int " and " si_ptr | |
53d30e45 | 336 | with the values specified by the sender of the signal; |
4176590c | 337 | see |
485ab701 | 338 | .BR sigqueue (3) |
4176590c | 339 | for more details. |
2e519bf2 | 340 | .IP * |
80752fa5 | 341 | Signals sent by POSIX.1b timers (since Linux 2.6) fill in |
c810983b MK |
342 | .I si_overrun |
343 | and | |
344 | .IR si_timerid . | |
345 | The | |
346 | .I si_timerid | |
347 | field is an internal ID used by the kernel to identify | |
348 | the timer; it is not the same as the timer ID returned by | |
804f03e6 | 349 | .BR timer_create (2). |
665f1e69 MK |
350 | The |
351 | .I si_overrun | |
352 | field is the timer overrun count; | |
353 | this is the same information as is obtained by a call to | |
354 | .BR timer_getoverrun (2). | |
355 | These fields are nonstandard Linux extensions. | |
c810983b | 356 | .IP * |
5ffadafd MK |
357 | Signals sent for message queue notification (see the description of |
358 | .B SIGEV_SIGNAL | |
359 | in | |
360 | .BR mq_notify (3)) | |
361 | fill in | |
362 | .IR si_int / si_ptr , | |
363 | with the | |
364 | .I sigev_value | |
365 | supplied to | |
366 | .BR mq_notify (3); | |
367 | .IR si_pid , | |
368 | with the process ID of the message sender; and | |
369 | .IR si_uid , | |
370 | with the real user ID of the message sender. | |
371 | .IP * | |
b7769f32 | 372 | .B SIGCHLD |
c810983b | 373 | fills in |
a797afac | 374 | .IR si_pid ", " si_uid ", " si_status ", " si_utime ", and " si_stime , |
665f1e69 MK |
375 | providing information about the child. |
376 | The | |
377 | .I si_pid | |
378 | field is the process ID of the child; | |
379 | .I si_uid | |
380 | is the child's real user ID. | |
381 | The | |
382 | .I si_status | |
383 | field contains the exit status of the child (if | |
384 | .I si_code | |
385 | is | |
386 | .BR CLD_EXITED ), | |
387 | or the signal number that caused the process to change state. | |
45f2d4eb MK |
388 | The |
389 | .I si_utime | |
390 | and | |
391 | .I si_stime | |
665f1e69 MK |
392 | contain the user and system CPU time used by the child process; |
393 | these fields do not include the times used by waited-for children (unlike | |
45f2d4eb MK |
394 | .BR getrusage (2) |
395 | and | |
7dd874ef | 396 | .BR times (2)). |
45f2d4eb MK |
397 | In kernels up to 2.6, and since 2.6.27, these fields report |
398 | CPU time in units of | |
399 | .IR sysconf(_SC_CLK_TCK) . | |
400 | In 2.6 kernels before 2.6.27, | |
401 | a bug meant that these fields reported time in units | |
402 | of the (configurable) system jiffy (see | |
403 | .BR time (7)). | |
665f1e69 | 404 | .\" FIXME . |
d03d9a05 MK |
405 | .\" When si_utime and si_stime where originally implemented, the |
406 | .\" measurement unit was HZ, which was the same as clock ticks | |
407 | .\" (sysconf(_SC_CLK_TCK)). In 2.6, HZ became configurable, and | |
408 | .\" was *still* used as the unit to return the info these fields, | |
2c8ae241 | 409 | .\" with the result that the field values depended on the |
d03d9a05 | 410 | .\" configured HZ. Of course, the should have been measured in |
00ac6ce4 | 411 | .\" USER_HZ instead, so that sysconf(_SC_CLK_TCK) could be used to |
d03d9a05 MK |
412 | .\" convert to seconds. I have a queued patch to fix this: |
413 | .\" http://thread.gmane.org/gmane.linux.kernel/698061/ . | |
45f2d4eb | 414 | .\" This patch made it into 2.6.27. |
d03d9a05 | 415 | .\" But note that these fields still don't return the times of |
17b78786 | 416 | .\" waited-for children (as is done by getrusage() and times() |
d03d9a05 | 417 | .\" and wait4()). Solaris 8 does include child times. |
2e519bf2 | 418 | .IP * |
c13182ef | 419 | .BR SIGILL , |
b7769f32 | 420 | .BR SIGFPE , |
c13182ef | 421 | .BR SIGSEGV , |
c2261e74 | 422 | .BR SIGBUS , |
b7769f32 | 423 | and |
c2261e74 | 424 | .BR SIGTRAP |
b7769f32 | 425 | fill in |
fea681da MK |
426 | .I si_addr |
427 | with the address of the fault. | |
c2261e74 MK |
428 | On some architectures, |
429 | these signals also fill in the | |
430 | .I si_trapno | |
7d082bab | 431 | field. |
a73a0781 | 432 | |
f402032c | 433 | Some suberrors of |
665f1e69 | 434 | .BR SIGBUS , |
f402032c AK |
435 | in particular |
436 | .B BUS_MCEERR_AO | |
437 | and | |
438 | .BR BUS_MCEERR_AR , | |
439 | also fill in | |
440 | .IR si_addr_lsb . | |
441 | This field indicates the least significant bit of the reported address | |
442 | and therefore the extent of the corruption. | |
443 | For example, if a full page was corrupted, | |
444 | .I si_addr_lsb | |
b911dcb0 | 445 | contains |
f402032c | 446 | .IR log2(sysconf(_SC_PAGESIZE)) . |
3b4a59c4 KC |
447 | When |
448 | .BR SIGTRAP | |
449 | is delivered in response to a | |
450 | .BR ptrace (2) | |
451 | event (PTRACE_EVENT_foo), | |
452 | .I si_addr | |
453 | is not populated, but | |
454 | .I si_pid | |
455 | and | |
456 | .I si_uid | |
457 | are populated with the respective process ID and user ID responsible for | |
e1954b03 MK |
458 | delivering the trap. |
459 | In the case of | |
c937b973 | 460 | .BR seccomp (2), |
3b4a59c4 | 461 | the tracee will be shown as delivering the event. |
a1d88c4c | 462 | .B BUS_MCEERR_* |
f402032c AK |
463 | and |
464 | .I si_addr_lsb | |
465 | are Linux-specific extensions. | |
0c962aab MK |
466 | |
467 | The | |
468 | .BR SEGV_BNDERR | |
469 | suberror of | |
470 | .B SIGSEGV | |
471 | populates | |
472 | .IR si_lower | |
473 | and | |
474 | .IR si_upper . | |
9f6007b8 MK |
475 | |
476 | The | |
477 | .BR SEGV_PKUERR | |
478 | suberror of | |
479 | .B SIGSEGV | |
480 | populates | |
481 | .IR si_pkey . | |
665f1e69 | 482 | .IP * |
dff6bb19 MK |
483 | .BR SIGIO / SIGPOLL |
484 | (the two names are synonyms on Linux) | |
b7769f32 | 485 | fills in |
fea681da | 486 | .IR si_band " and " si_fd . |
665f1e69 MK |
487 | The |
488 | .I si_band | |
489 | event is a bit mask containing the same values as are filled in the | |
490 | .I revents | |
491 | field by | |
492 | .BR poll (2). | |
493 | The | |
494 | .I si_fd | |
b1f91dc1 MK |
495 | field indicates the file descriptor for which the I/O event occurred; |
496 | for further details, see the description of | |
5ffdc2fd | 497 | .BR F_SETSIG |
b1f91dc1 MK |
498 | in |
499 | .BR fcntl (2). | |
bcd0ba54 | 500 | .IP * |
a1d88c4c | 501 | .BR SIGSYS , |
b11bccf8 | 502 | generated (since Linux 3.5) |
bcd0ba54 | 503 | .\" commit a0727e8ce513fe6890416da960181ceb10fbfae6 |
b11bccf8 MK |
504 | when a seccomp filter returns |
505 | .BR SECCOMP_RET_TRAP , | |
bcd0ba54 MK |
506 | fills in |
507 | .IR si_call_addr , | |
508 | .IR si_syscall , | |
509 | .IR si_arch , | |
3b4a59c4 KC |
510 | .IR si_errno , |
511 | and other fields as described in | |
bcd0ba54 | 512 | .BR seccomp (2). |
2e519bf2 | 513 | .PP |
fea681da | 514 | .I si_code |
e1954b03 MK |
515 | is a value (not a bit mask) indicating why this signal was sent. |
516 | For a | |
3b4a59c4 KC |
517 | .BR ptrace (2) |
518 | event, | |
519 | .I si_code | |
520 | will contain | |
521 | .BR SIGTRAP | |
522 | and have the ptrace event in the high byte: | |
523 | ||
524 | .nf | |
525 | (SIGTRAP | PTRACE_EVENT_foo << 8). | |
526 | .fi | |
527 | ||
528 | For a regular signal, the following list shows the values which can be | |
529 | placed in | |
1812a949 MK |
530 | .I si_code |
531 | for any signal, along with reason that the signal was generated. | |
532 | .RS 4 | |
d443e2fa | 533 | .TP |
1812a949 | 534 | .B SI_USER |
ff953a8d | 535 | .BR kill (2). |
1812a949 MK |
536 | .TP |
537 | .B SI_KERNEL | |
538 | Sent by the kernel. | |
539 | .TP | |
540 | .B SI_QUEUE | |
ff953a8d | 541 | .BR sigqueue (3). |
1812a949 MK |
542 | .TP |
543 | .B SI_TIMER | |
ff953a8d | 544 | POSIX timer expired. |
1812a949 | 545 | .TP |
eb83484f MK |
546 | .BR SI_MESGQ " (since Linux 2.6.6)" |
547 | POSIX message queue state changed; see | |
ff953a8d | 548 | .BR mq_notify (3). |
1812a949 MK |
549 | .TP |
550 | .B SI_ASYNCIO | |
ff953a8d | 551 | AIO completed. |
1812a949 MK |
552 | .TP |
553 | .B SI_SIGIO | |
dff6bb19 MK |
554 | Queued |
555 | .B SIGIO | |
556 | (only in kernels up to Linux 2.2; from Linux 2.4 onward | |
557 | .BR SIGIO / SIGPOLL | |
558 | fills in | |
559 | .I si_code | |
560 | as described below). | |
1812a949 | 561 | .TP |
eb83484f | 562 | .BR SI_TKILL " (since Linux 2.4.19)" |
1812a949 MK |
563 | .BR tkill (2) |
564 | or | |
ff953a8d | 565 | .BR tgkill (2). |
92057f4d | 566 | .\" SI_DETHREAD is defined in 2.6.9 sources, but isn't implemented |
c13182ef | 567 | .\" It appears to have been an idea that was tried during 2.5.6 |
92057f4d | 568 | .\" through to 2.5.24 and then was backed out. |
1812a949 MK |
569 | .RE |
570 | .PP | |
6beb1671 | 571 | The following values can be placed in |
1812a949 MK |
572 | .I si_code |
573 | for a | |
574 | .B SIGILL | |
575 | signal: | |
576 | .RS 4 | |
d443e2fa | 577 | .TP |
1812a949 | 578 | .B ILL_ILLOPC |
ff953a8d | 579 | Illegal opcode. |
1812a949 MK |
580 | .TP |
581 | .B ILL_ILLOPN | |
ff953a8d | 582 | Illegal operand. |
1812a949 MK |
583 | .TP |
584 | .B ILL_ILLADR | |
ff953a8d | 585 | Illegal addressing mode. |
1812a949 MK |
586 | .TP |
587 | .B ILL_ILLTRP | |
ff953a8d | 588 | Illegal trap. |
1812a949 MK |
589 | .TP |
590 | .B ILL_PRVOPC | |
ff953a8d | 591 | Privileged opcode. |
1812a949 MK |
592 | .TP |
593 | .B ILL_PRVREG | |
ff953a8d | 594 | Privileged register. |
1812a949 MK |
595 | .TP |
596 | .B ILL_COPROC | |
ff953a8d | 597 | Coprocessor error. |
1812a949 MK |
598 | .TP |
599 | .B ILL_BADSTK | |
ff953a8d | 600 | Internal stack error. |
1812a949 MK |
601 | .RE |
602 | .PP | |
6beb1671 | 603 | The following values can be placed in |
1812a949 MK |
604 | .I si_code |
605 | for a | |
606 | .B SIGFPE | |
607 | signal: | |
608 | .RS 4 | |
d443e2fa | 609 | .TP |
1812a949 | 610 | .B FPE_INTDIV |
ff953a8d | 611 | Integer divide by zero. |
1812a949 MK |
612 | .TP |
613 | .B FPE_INTOVF | |
ff953a8d | 614 | Integer overflow. |
1812a949 MK |
615 | .TP |
616 | .B FPE_FLTDIV | |
ff953a8d | 617 | Floating-point divide by zero. |
1812a949 MK |
618 | .TP |
619 | .B FPE_FLTOVF | |
ff953a8d | 620 | Floating-point overflow. |
1812a949 MK |
621 | .TP |
622 | .B FPE_FLTUND | |
ff953a8d | 623 | Floating-point underflow. |
1812a949 MK |
624 | .TP |
625 | .B FPE_FLTRES | |
ff953a8d | 626 | Floating-point inexact result. |
1812a949 MK |
627 | .TP |
628 | .B FPE_FLTINV | |
ff953a8d | 629 | Floating-point invalid operation. |
1812a949 MK |
630 | .TP |
631 | .B FPE_FLTSUB | |
ff953a8d | 632 | Subscript out of range. |
1812a949 MK |
633 | .RE |
634 | .PP | |
6beb1671 | 635 | The following values can be placed in |
1812a949 MK |
636 | .I si_code |
637 | for a | |
638 | .B SIGSEGV | |
639 | signal: | |
640 | .RS 4 | |
d443e2fa | 641 | .TP |
1812a949 | 642 | .B SEGV_MAPERR |
ff953a8d | 643 | Address not mapped to object. |
1812a949 MK |
644 | .TP |
645 | .B SEGV_ACCERR | |
ff953a8d | 646 | Invalid permissions for mapped object. |
0c962aab MK |
647 | .TP |
648 | .BR SEGV_BNDERR " (since Linux 3.19)" | |
649 | .\" commit ee1b58d36aa1b5a79eaba11f5c3633c88231da83 | |
650 | Failed address bound checks. | |
9f6007b8 MK |
651 | .TP |
652 | .BR SEGV_PKUERR " (since Linux 4.6)" | |
653 | .\" commit cd0ea35ff5511cde299a61c21a95889b4a71464e | |
bc2983d6 DH |
654 | Access was denied by memory protection keys. |
655 | See | |
656 | .BR pkeys (7). | |
657 | The protection key which applied to this access is available via | |
658 | .IR si_pkey . | |
1812a949 MK |
659 | .RE |
660 | .PP | |
6beb1671 | 661 | The following values can be placed in |
1812a949 MK |
662 | .I si_code |
663 | for a | |
664 | .B SIGBUS | |
665 | signal: | |
666 | .RS 4 | |
d443e2fa | 667 | .TP |
1812a949 | 668 | .B BUS_ADRALN |
ff953a8d | 669 | Invalid address alignment. |
1812a949 MK |
670 | .TP |
671 | .B BUS_ADRERR | |
ff953a8d | 672 | Nonexistent physical address. |
1812a949 MK |
673 | .TP |
674 | .B BUS_OBJERR | |
ff953a8d | 675 | Object-specific hardware error. |
f402032c AK |
676 | .TP |
677 | .BR BUS_MCEERR_AR " (since Linux 2.6.32)" | |
678 | Hardware memory error consumed on a machine check; action required. | |
679 | .TP | |
680 | .BR BUS_MCEERR_AO " (since Linux 2.6.32)" | |
681 | Hardware memory error detected in process but not consumed; action optional. | |
1812a949 MK |
682 | .RE |
683 | .PP | |
6beb1671 | 684 | The following values can be placed in |
1812a949 MK |
685 | .I si_code |
686 | for a | |
687 | .B SIGTRAP | |
688 | signal: | |
689 | .RS 4 | |
d443e2fa | 690 | .TP |
1812a949 | 691 | .B TRAP_BRKPT |
ff953a8d | 692 | Process breakpoint. |
1812a949 MK |
693 | .TP |
694 | .B TRAP_TRACE | |
ff953a8d | 695 | Process trace trap. |
39efed93 MK |
696 | .TP |
697 | .BR TRAP_BRANCH " (since Linux 2.4)" | |
ff953a8d | 698 | Process taken branch trap. |
39efed93 MK |
699 | .TP |
700 | .BR TRAP_HWBKPT " (since Linux 2.4)" | |
ff953a8d | 701 | Hardware breakpoint/watchpoint. |
1812a949 MK |
702 | .RE |
703 | .PP | |
6beb1671 | 704 | The following values can be placed in |
1812a949 MK |
705 | .I si_code |
706 | for a | |
688e23c6 | 707 | .B SIGCHLD |
1812a949 MK |
708 | signal: |
709 | .RS 4 | |
d443e2fa | 710 | .TP |
1812a949 | 711 | .B CLD_EXITED |
ff953a8d | 712 | Child has exited. |
1812a949 MK |
713 | .TP |
714 | .B CLD_KILLED | |
ff953a8d | 715 | Child was killed. |
1812a949 MK |
716 | .TP |
717 | .B CLD_DUMPED | |
ff953a8d | 718 | Child terminated abnormally. |
1812a949 MK |
719 | .TP |
720 | .B CLD_TRAPPED | |
ff953a8d | 721 | Traced child has trapped. |
1812a949 MK |
722 | .TP |
723 | .B CLD_STOPPED | |
ff953a8d | 724 | Child has stopped. |
1812a949 | 725 | .TP |
eb83484f | 726 | .BR CLD_CONTINUED " (since Linux 2.6.9)" |
ff953a8d | 727 | Stopped child has continued. |
1812a949 MK |
728 | .RE |
729 | .PP | |
6beb1671 | 730 | The following values can be placed in |
1812a949 MK |
731 | .I si_code |
732 | for a | |
dff6bb19 | 733 | .BR SIGIO / SIGPOLL |
1812a949 MK |
734 | signal: |
735 | .RS 4 | |
d443e2fa | 736 | .TP |
1812a949 | 737 | .B POLL_IN |
ff953a8d | 738 | Data input available. |
1812a949 MK |
739 | .TP |
740 | .B POLL_OUT | |
ff953a8d | 741 | Output buffers available. |
1812a949 MK |
742 | .TP |
743 | .B POLL_MSG | |
ff953a8d | 744 | Input message available. |
1812a949 MK |
745 | .TP |
746 | .B POLL_ERR | |
ff953a8d | 747 | I/O error. |
1812a949 MK |
748 | .TP |
749 | .B POLL_PRI | |
ff953a8d | 750 | High priority input available. |
1812a949 MK |
751 | .TP |
752 | .B POLL_HUP | |
ff953a8d | 753 | Device disconnected. |
1812a949 | 754 | .RE |
3b4a59c4 KC |
755 | .PP |
756 | The following value can be placed in | |
757 | .I si_code | |
758 | for a | |
759 | .BR SIGSYS | |
760 | signal: | |
761 | .RS 4 | |
d443e2fa | 762 | .TP |
3b4a59c4 | 763 | .BR SYS_SECCOMP " (since Linux 3.5)" |
ff953a8d | 764 | Triggered by a |
3b4a59c4 | 765 | .BR seccomp (2) |
ff953a8d | 766 | filter rule. |
3b4a59c4 | 767 | .RE |
47297adb | 768 | .SH RETURN VALUE |
00161f1b | 769 | .BR sigaction () |
de86e93c MK |
770 | returns 0 on success; on error, \-1 is returned, and |
771 | .I errno | |
772 | is set to indicate the error. | |
fea681da MK |
773 | .SH ERRORS |
774 | .TP | |
775 | .B EFAULT | |
00161f1b MK |
776 | .IR act " or " oldact |
777 | points to memory which is not a valid part of the process address space. | |
fea681da MK |
778 | .TP |
779 | .B EINVAL | |
c13182ef MK |
780 | An invalid signal was specified. |
781 | This will also be generated if an attempt | |
fea681da MK |
782 | is made to change the action for |
783 | .BR SIGKILL " or " SIGSTOP ", " | |
00161f1b | 784 | which cannot be caught or ignored. |
47297adb | 785 | .SH CONFORMING TO |
ab8cd127 | 786 | POSIX.1-2001, POSIX.1-2008, SVr4. |
2dd578fd | 787 | .\" SVr4 does not document the EINTR condition. |
fea681da | 788 | .SH NOTES |
3fb46b2b | 789 | A child created via |
0ac0def4 MK |
790 | .BR fork (2) |
791 | inherits a copy of its parent's signal dispositions. | |
792 | During an | |
793 | .BR execve (2), | |
794 | the dispositions of handled signals are reset to the default; | |
795 | the dispositions of ignored signals are left unchanged. | |
796 | ||
d9bfdb9c | 797 | According to POSIX, the behavior of a process is undefined after it |
b7769f32 MK |
798 | ignores a |
799 | .BR SIGFPE , | |
800 | .BR SIGILL , | |
801 | or | |
0daa9e92 | 802 | .B SIGSEGV |
b7769f32 | 803 | signal that was not generated by |
0bfa087b | 804 | .BR kill (2) |
b7769f32 | 805 | or |
0bfa087b | 806 | .BR raise (3). |
fea681da | 807 | Integer division by zero has undefined result. |
b7769f32 MK |
808 | On some architectures it will generate a |
809 | .B SIGFPE | |
810 | signal. | |
8bd58774 MK |
811 | (Also dividing the most negative integer by \-1 may generate |
812 | .BR SIGFPE .) | |
fea681da MK |
813 | Ignoring this signal might lead to an endless loop. |
814 | .PP | |
b7769f32 MK |
815 | POSIX.1-1990 disallowed setting the action for |
816 | .B SIGCHLD | |
817 | to | |
818 | .BR SIG_IGN . | |
ab8cd127 | 819 | POSIX.1-2001 and later allow this possibility, so that ignoring |
b7769f32 MK |
820 | .B SIGCHLD |
821 | can be used to prevent the creation of zombies (see | |
822 | .BR wait (2)). | |
efbfd7ec | 823 | Nevertheless, the historical BSD and System\ V behaviors for ignoring |
b7769f32 MK |
824 | .B SIGCHLD |
825 | differ, so that the only completely portable method of ensuring that | |
826 | terminated children do not become zombies is to catch the | |
827 | .B SIGCHLD | |
828 | signal and perform a | |
829 | .BR wait (2) | |
830 | or similar. | |
fea681da | 831 | .PP |
33a0ccb2 | 832 | POSIX.1-1990 specified only |
fea681da | 833 | .BR SA_NOCLDSTOP . |
b7769f32 | 834 | POSIX.1-2001 added |
e6a773f6 | 835 | .BR SA_NOCLDSTOP , |
b7769f32 | 836 | .BR SA_NOCLDWAIT , |
b7769f32 | 837 | .BR SA_NODEFER , |
e6a773f6 MK |
838 | .BR SA_ONSTACK , |
839 | .BR SA_RESETHAND , | |
840 | .BR SA_RESTART , | |
b7769f32 MK |
841 | and |
842 | .BR SA_SIGINFO . | |
843 | Use of these latter values in | |
fea681da | 844 | .I sa_flags |
b7769f32 | 845 | may be less portable in applications intended for older |
008f1ecc | 846 | UNIX implementations. |
b7769f32 | 847 | .PP |
fea681da MK |
848 | The |
849 | .B SA_RESETHAND | |
850 | flag is compatible with the SVr4 flag of the same name. | |
851 | .PP | |
852 | The | |
853 | .B SA_NODEFER | |
854 | flag is compatible with the SVr4 flag of the same name under kernels | |
c13182ef MK |
855 | 1.3.9 and newer. |
856 | On older kernels the Linux implementation | |
fea681da MK |
857 | allowed the receipt of any signal, not just the one we are installing |
858 | (effectively overriding any | |
859 | .I sa_mask | |
860 | settings). | |
fea681da | 861 | .PP |
b7769f32 | 862 | .BR sigaction () |
460b3d61 | 863 | can be called with a NULL second argument to query the current signal |
c13182ef MK |
864 | handler. |
865 | It can also be used to check whether a given signal is valid for | |
460b3d61 | 866 | the current machine by calling it with NULL second and third arguments. |
fea681da | 867 | .PP |
c13182ef | 868 | It is not possible to block |
00161f1b MK |
869 | .BR SIGKILL " or " SIGSTOP |
870 | (by specifying them in | |
871 | .IR sa_mask ). | |
872 | Attempts to do so are silently ignored. | |
873 | .PP | |
fea681da MK |
874 | See |
875 | .BR sigsetops (3) | |
876 | for details on manipulating signal sets. | |
2e519bf2 MK |
877 | .PP |
878 | See | |
879 | .BR signal (7) | |
988db661 | 880 | for a list of the async-signal-safe functions that can be |
2e519bf2 | 881 | safely called inside from inside a signal handler. |
1545ed95 | 882 | .\" |
0722a578 | 883 | .SS C library/kernel differences |
ee053db8 MK |
884 | The glibc wrapper function for |
885 | .BR sigaction () | |
886 | gives an error | |
887 | .RB ( EINVAL ) | |
888 | on attempts to change the disposition of the two real-time signals | |
889 | used internally by the NPTL threading implementation. | |
890 | See | |
891 | .BR nptl (7) | |
892 | for details. | |
893 | ||
1545ed95 MK |
894 | The original Linux system call was named |
895 | .BR sigaction (). | |
896 | However, with the addition of real-time signals in Linux 2.2, | |
897 | the fixed-size, 32-bit | |
898 | .IR sigset_t | |
899 | type supported by that system call was no longer fit for purpose. | |
900 | Consequently, a new system call, | |
901 | .BR rt_sigaction (), | |
902 | was added to support an enlarged | |
903 | .IR sigset_t | |
904 | type. | |
905 | The new system call takes a fourth argument, | |
906 | .IR "size_t sigsetsize" , | |
907 | which specifies the size in bytes of the signal sets in | |
908 | .IR act.sa_mask | |
909 | and | |
910 | .IR oldact.sa_mask . | |
911 | This argument is currently required to have the value | |
912 | .IR sizeof(sigset_t) | |
913 | (or the error | |
914 | .B EINVAL | |
915 | results). | |
916 | The glibc | |
917 | .BR sigaction () | |
918 | wrapper function hides these details from us, transparently calling | |
919 | .BR rt_sigaction () | |
920 | when the kernel provides it. | |
921 | .\" | |
4a19cb8c MK |
922 | .SS Undocumented |
923 | Before the introduction of | |
d231b918 | 924 | .BR SA_SIGINFO , |
4a19cb8c MK |
925 | it was also possible to get some additional information, |
926 | namely by using a | |
927 | .I sa_handler | |
928 | with second argument of type | |
929 | .IR "struct sigcontext". | |
66a9882e | 930 | See the relevant Linux kernel sources for details. |
4a19cb8c | 931 | This use is obsolete now. |
00161f1b MK |
932 | .SH BUGS |
933 | In kernels up to and including 2.6.13, specifying | |
934 | .B SA_NODEFER | |
935 | in | |
936 | .I sa_flags | |
437a9182 | 937 | prevents not only the delivered signal from being masked during |
00161f1b MK |
938 | execution of the handler, but also the signals specified in |
939 | .IR sa_mask . | |
0643ee28 | 940 | This bug was fixed in kernel 2.6.14. |
af5267b2 MK |
941 | .SH EXAMPLE |
942 | See | |
943 | .BR mprotect (2). | |
47297adb | 944 | .SH SEE ALSO |
fea681da MK |
945 | .BR kill (1), |
946 | .BR kill (2), | |
fea681da | 947 | .BR pause (2), |
d806bc05 | 948 | .BR restart_syscall (2), |
3b4a59c4 | 949 | .BR seccomp (2) |
fea681da MK |
950 | .BR sigaltstack (2), |
951 | .BR signal (2), | |
058c1165 | 952 | .BR signalfd (2), |
00161f1b MK |
953 | .BR sigpending (2), |
954 | .BR sigprocmask (2), | |
59fc0ad1 | 955 | .BR sigreturn (2), |
00161f1b | 956 | .BR sigsuspend (2), |
b7769f32 | 957 | .BR wait (2), |
498aad50 | 958 | .BR killpg (3), |
fea681da MK |
959 | .BR raise (3), |
960 | .BR siginterrupt (3), | |
485ab701 | 961 | .BR sigqueue (3), |
fea681da | 962 | .BR sigsetops (3), |
30ecea55 | 963 | .BR sigvec (3), |
e1a9bc1b | 964 | .BR core (5), |
fea681da | 965 | .BR signal (7) |