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