| blob | 812c5fd25f4c26f65315f95c6874ba02510b376b |
1 '\" t
2 .\" Copyright (c) 1994,1995 Mike Battersby <mib@deakin.edu.au>
3 .\" and Copyright 2004, 2005 Michael Kerrisk <mtk.manpages@gmail.com>
4 .\" based on work by faith@cs.unc.edu
5 .\"
6 .\" %%%LICENSE_START(VERBATIM)
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.
15 .\"
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.
23 .\"
24 .\" Formatted or processed versions of this manual, if unaccompanied by
25 .\" the source, must acknowledge the copyright and authors of this work.
26 .\" %%%LICENSE_END
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.
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
35 .\" Modified 2004-11-11 by Michael Kerrisk <mtk.manpages@gmail.com>
36 .\" Added mention of SIGCONT under SA_NOCLDSTOP
37 .\" Added SA_NOCLDWAIT
38 .\" Modified 2004-11-17 by Michael Kerrisk <mtk.manpages@gmail.com>
39 .\" Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags.
40 .\" Formatting fixes
41 .\" 2004-12-09, mtk, added SI_TKILL + other minor changes
42 .\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend()
43 .\" out of this page into separate pages.
44 .\" 2010-06-11 Andi Kleen, add hwpoison signal extensions
45 .\" 2010-06-11 mtk, improvements to discussion of various siginfo_t fields.
46 .\" 2015-01-17, Kees Cook <keescook@chromium.org>
47 .\" Added notes on ptrace SIGTRAP and SYS_SECCOMP.
48 .\"
49 .TH SIGACTION 2 2017-05-03 "Linux" "Linux Programmer's Manual"
50 .SH NAME
51 sigaction, rt_sigaction \- examine and change a signal action
52 .SH SYNOPSIS
53 .nf
54 .B #include <signal.h>
55 .sp
56 .BI "int sigaction(int " signum ", const struct sigaction *" act ,
57 .BI " struct sigaction *" oldact );
58 .fi
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
69 .IR siginfo_t :
70 _POSIX_C_SOURCE >= 199309L
71 .ad b
72 .SH DESCRIPTION
73 The
74 .BR sigaction ()
75 system call is used to change the action taken by a process on
76 receipt of a specific signal.
77 (See
78 .BR signal (7)
79 for an overview of signals.)
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
89 is non-NULL, the new action for signal
90 .I signum
91 is installed from
92 .IR act .
93 If
94 .I oldact
95 is non-NULL, the previous action is saved in
96 .IR oldact .
97 .PP
98 The
99 .I sigaction
100 structure is defined as something like:
101 .sp
102 .in +4n
103 .nf
104 struct sigaction {
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);
110 };
111 .fi
112 .in
113 .PP
114 On some architectures a union is involved: do not assign to both
115 .I sa_handler
116 and
117 .IR sa_sigaction .
118 .PP
119 The
120 .I sa_restorer
121 field is not intended for application use.
122 (POSIX does not specify a
123 .I sa_restorer
124 field.)
125 Some further details of purpose of this field can be found in
126 .BR sigreturn (2).
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
133 for the default action,
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
138 If
139 .B SA_SIGINFO
140 is specified in
141 .IR sa_flags ,
142 then
143 .I sa_sigaction
144 (instead of
145 .IR sa_handler )
146 specifies the signal-handling function for
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
153 (cast to \fIvoid\ *\fP) as its third argument.
154 (Commonly, the handler function doesn't make any use of the third argument.
155 See
156 .BR getcontext (3)
157 for further information about
158 .IR ucontext_t .)
159 .PP
160 .I sa_mask
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.
165 In addition, the signal which triggered the handler
166 will be blocked, unless the
167 .B SA_NODEFER
168 flag is used.
169 .PP
170 .I sa_flags
171 specifies a set of flags which modify the behavior of the signal.
172 It is formed by the bitwise OR of zero or more of the following:
173 .RS 4
174 .TP
175 .B SA_NOCLDSTOP
176 If
177 .I signum
178 is
179 .BR SIGCHLD ,
180 do not receive notification when child processes stop (i.e., when they
181 receive one of
182 .BR SIGSTOP ", " SIGTSTP ", " SIGTTIN ", "
183 or
184 .BR SIGTTOU )
185 or resume (i.e., they receive
186 .BR SIGCONT )
187 (see
188 .BR wait (2)).
189 This flag is meaningful only when establishing a handler for
190 .BR SIGCHLD .
191 .TP
192 .BR SA_NOCLDWAIT " (since Linux 2.6)"
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
200 .BR waitpid (2).
201 This flag is meaningful only when establishing a handler for
202 .BR SIGCHLD ,
203 or when setting that signal's disposition to
204 .BR SIG_DFL .
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.
217 .TP
218 .B SA_NODEFER
219 Do not prevent the signal from being received from within its own signal
220 handler.
221 This flag is meaningful only when establishing a signal handler.
222 .B SA_NOMASK
223 is an obsolete, nonstandard synonym for this flag.
224 .TP
225 .B SA_ONSTACK
226 Call the signal handler on an alternate signal stack provided by
227 .BR sigaltstack (2).
228 If an alternate stack is not available, the default stack will be used.
229 This flag is meaningful only when establishing a signal handler.
230 .TP
231 .BR SA_RESETHAND
232 Restore the signal action to the default upon entry to the signal handler.
233 This flag is meaningful only when establishing a signal handler.
234 .B SA_ONESHOT
235 is an obsolete, nonstandard synonym for this flag.
236 .TP
237 .B SA_RESTART
238 Provide behavior compatible with BSD signal semantics by making certain
239 system calls restartable across signals.
240 This flag is meaningful only when establishing a signal handler.
241 See
242 .BR signal (7)
243 for a discussion of system call restarting.
244 .TP
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
254 .BR SA_SIGINFO " (since Linux 2.2)"
255 The signal handler takes three arguments, not one.
256 In this case,
257 .I sa_sigaction
258 should be set instead of
259 .IR sa_handler .
260 This flag is meaningful only when establishing a signal handler.
261 .\" (The
262 .\" .I sa_sigaction
263 .\" field was added in Linux 2.1.86.)
264 .RE
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:
275 .nf
276 .in +4n
277 void
278 handler(int sig, siginfo_t *info, void *ucontext)
279 {
280 ...
281 }
282 .in
283 .fi
285 The
286 .I siginfo_t
287 data type is a structure with the following fields:
288 .sp
289 .in +4n
290 .nf
291 siginfo_t {
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) */
298 .\" FIXME
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.
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 */
313 .\" In the kernel: si_tid
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) */
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) */
324 int si_pkey; /* Protection key on PTE that caused
325 fault (since Linux 4.6) */
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) */
332 }
333 .fi
334 .in
336 .IR si_signo ", " si_errno " and " si_code
337 are defined for all signals.
338 .RI ( si_errno
339 is generally unused on Linux.)
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:
342 .IP * 2
343 Signals sent with
344 .BR kill (2)
345 and
346 .BR sigqueue (3)
347 fill in
348 .IR si_pid " and " si_uid .
349 In addition, signals sent with
350 .BR sigqueue (3)
351 fill in
352 .IR si_int " and " si_ptr
353 with the values specified by the sender of the signal;
354 see
355 .BR sigqueue (3)
356 for more details.
357 .IP *
358 Signals sent by POSIX.1b timers (since Linux 2.6) fill in
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
366 .BR timer_create (2).
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.
373 .IP *
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 *
389 .B SIGCHLD
390 fills in
391 .IR si_pid ", " si_uid ", " si_status ", " si_utime ", and " si_stime ,
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.
405 The
406 .I si_utime
407 and
408 .I si_stime
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
411 .BR getrusage (2)
412 and
413 .BR times (2)).
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)).
421 .\" FIXME .
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,
426 .\" with the result that the field values depended on the
427 .\" configured HZ. Of course, the should have been measured in
428 .\" USER_HZ instead, so that sysconf(_SC_CLK_TCK) could be used to
429 .\" convert to seconds. I have a queued patch to fix this:
430 .\" http://thread.gmane.org/gmane.linux.kernel/698061/ .
431 .\" This patch made it into 2.6.27.
432 .\" But note that these fields still don't return the times of
433 .\" waited-for children (as is done by getrusage() and times()
434 .\" and wait4()). Solaris 8 does include child times.
435 .IP *
436 .BR SIGILL ,
437 .BR SIGFPE ,
438 .BR SIGSEGV ,
439 .BR SIGBUS ,
440 and
441 .BR SIGTRAP
442 fill in
443 .I si_addr
444 with the address of the fault.
445 On some architectures,
446 these signals also fill in the
447 .I si_trapno
448 field.
450 Some suberrors of
451 .BR SIGBUS ,
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
462 contains
463 .IR log2(sysconf(_SC_PAGESIZE)) .
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
475 delivering the trap.
476 In the case of
477 .BR seccomp (2),
478 the tracee will be shown as delivering the event.
479 .B BUS_MCEERR_*
480 and
481 .I si_addr_lsb
482 are Linux-specific extensions.
484 The
485 .BR SEGV_BNDERR
486 suberror of
487 .B SIGSEGV
488 populates
489 .IR si_lower
490 and
491 .IR si_upper .
493 The
494 .BR SEGV_PKUERR
495 suberror of
496 .B SIGSEGV
497 populates
498 .IR si_pkey .
499 .IP *
500 .BR SIGIO / SIGPOLL
501 (the two names are synonyms on Linux)
502 fills in
503 .IR si_band " and " si_fd .
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
512 field indicates the file descriptor for which the I/O event occurred;
513 for further details, see the description of
514 .BR F_SETSIG
515 in
516 .BR fcntl (2).
517 .IP *
518 .BR SIGSYS ,
519 generated (since Linux 3.5)
520 .\" commit a0727e8ce513fe6890416da960181ceb10fbfae6
521 when a seccomp filter returns
522 .BR SECCOMP_RET_TRAP ,
523 fills in
524 .IR si_call_addr ,
525 .IR si_syscall ,
526 .IR si_arch ,
527 .IR si_errno ,
528 and other fields as described in
529 .BR seccomp (2).
530 .\"
531 .SS
532 The si_code field
533 The
534 .I si_code
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.
541 For a
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:
549 .nf
550 (SIGTRAP | PTRACE_EVENT_foo << 8).
551 .fi
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
581 For a regular signal, the following list shows the values which can be
582 placed in
583 .I si_code
584 for any signal, along with the reason that the signal was generated.
585 .RS 4
586 .TP
587 .B SI_USER
588 .BR kill (2).
589 .TP
590 .B SI_KERNEL
591 Sent by the kernel.
592 .TP
593 .B SI_QUEUE
594 .BR sigqueue (3).
595 .TP
596 .B SI_TIMER
597 POSIX timer expired.
598 .TP
599 .BR SI_MESGQ " (since Linux 2.6.6)"
600 POSIX message queue state changed; see
601 .BR mq_notify (3).
602 .TP
603 .B SI_ASYNCIO
604 AIO completed.
605 .TP
606 .B SI_SIGIO
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).
614 .TP
615 .BR SI_TKILL " (since Linux 2.4.19)"
616 .BR tkill (2)
617 or
618 .BR tgkill (2).
619 .\" SI_DETHREAD is defined in 2.6.9 sources, but isn't implemented
620 .\" It appears to have been an idea that was tried during 2.5.6
621 .\" through to 2.5.24 and then was backed out.
622 .RE
623 .PP
624 The following values can be placed in
625 .I si_code
626 for a
627 .B SIGILL
628 signal:
629 .RS 4
630 .TP
631 .B ILL_ILLOPC
632 Illegal opcode.
633 .TP
634 .B ILL_ILLOPN
635 Illegal operand.
636 .TP
637 .B ILL_ILLADR
638 Illegal addressing mode.
639 .TP
640 .B ILL_ILLTRP
641 Illegal trap.
642 .TP
643 .B ILL_PRVOPC
644 Privileged opcode.
645 .TP
646 .B ILL_PRVREG
647 Privileged register.
648 .TP
649 .B ILL_COPROC
650 Coprocessor error.
651 .TP
652 .B ILL_BADSTK
653 Internal stack error.
654 .RE
655 .PP
656 The following values can be placed in
657 .I si_code
658 for a
659 .B SIGFPE
660 signal:
661 .RS 4
662 .TP
663 .B FPE_INTDIV
664 Integer divide by zero.
665 .TP
666 .B FPE_INTOVF
667 Integer overflow.
668 .TP
669 .B FPE_FLTDIV
670 Floating-point divide by zero.
671 .TP
672 .B FPE_FLTOVF
673 Floating-point overflow.
674 .TP
675 .B FPE_FLTUND
676 Floating-point underflow.
677 .TP
678 .B FPE_FLTRES
679 Floating-point inexact result.
680 .TP
681 .B FPE_FLTINV
682 Floating-point invalid operation.
683 .TP
684 .B FPE_FLTSUB
685 Subscript out of range.
686 .RE
687 .PP
688 The following values can be placed in
689 .I si_code
690 for a
691 .B SIGSEGV
692 signal:
693 .RS 4
694 .TP
695 .B SEGV_MAPERR
696 Address not mapped to object.
697 .TP
698 .B SEGV_ACCERR
699 Invalid permissions for mapped object.
700 .TP
701 .BR SEGV_BNDERR " (since Linux 3.19)"
702 .\" commit ee1b58d36aa1b5a79eaba11f5c3633c88231da83
703 Failed address bound checks.
704 .TP
705 .BR SEGV_PKUERR " (since Linux 4.6)"
706 .\" commit cd0ea35ff5511cde299a61c21a95889b4a71464e
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 .
712 .RE
713 .PP
714 The following values can be placed in
715 .I si_code
716 for a
717 .B SIGBUS
718 signal:
719 .RS 4
720 .TP
721 .B BUS_ADRALN
722 Invalid address alignment.
723 .TP
724 .B BUS_ADRERR
725 Nonexistent physical address.
726 .TP
727 .B BUS_OBJERR
728 Object-specific hardware error.
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.
735 .RE
736 .PP
737 The following values can be placed in
738 .I si_code
739 for a
740 .B SIGTRAP
741 signal:
742 .RS 4
743 .TP
744 .B TRAP_BRKPT
745 Process breakpoint.
746 .TP
747 .B TRAP_TRACE
748 Process trace trap.
749 .TP
750 .BR TRAP_BRANCH " (since Linux 2.4, IA64 only))"
751 Process taken branch trap.
752 .TP
753 .BR TRAP_HWBKPT " (since Linux 2.4, IA64 only))"
754 Hardware breakpoint/watchpoint.
755 .RE
756 .PP
757 The following values can be placed in
758 .I si_code
759 for a
760 .B SIGCHLD
761 signal:
762 .RS 4
763 .TP
764 .B CLD_EXITED
765 Child has exited.
766 .TP
767 .B CLD_KILLED
768 Child was killed.
769 .TP
770 .B CLD_DUMPED
771 Child terminated abnormally.
772 .TP
773 .B CLD_TRAPPED
774 Traced child has trapped.
775 .TP
776 .B CLD_STOPPED
777 Child has stopped.
778 .TP
779 .BR CLD_CONTINUED " (since Linux 2.6.9)"
780 Stopped child has continued.
781 .RE
782 .PP
783 The following values can be placed in
784 .I si_code
785 for a
786 .BR SIGIO / SIGPOLL
787 signal:
788 .RS 4
789 .TP
790 .B POLL_IN
791 Data input available.
792 .TP
793 .B POLL_OUT
794 Output buffers available.
795 .TP
796 .B POLL_MSG
797 Input message available.
798 .TP
799 .B POLL_ERR
800 I/O error.
801 .TP
802 .B POLL_PRI
803 High priority input available.
804 .TP
805 .B POLL_HUP
806 Device disconnected.
807 .RE
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
815 .TP
816 .BR SYS_SECCOMP " (since Linux 3.5)"
817 Triggered by a
818 .BR seccomp (2)
819 filter rule.
820 .RE
821 .SH RETURN VALUE
822 .BR sigaction ()
823 returns 0 on success; on error, \-1 is returned, and
824 .I errno
825 is set to indicate the error.
826 .SH ERRORS
827 .TP
828 .B EFAULT
829 .IR act " or " oldact
830 points to memory which is not a valid part of the process address space.
831 .TP
832 .B EINVAL
833 An invalid signal was specified.
834 This will also be generated if an attempt
835 is made to change the action for
836 .BR SIGKILL " or " SIGSTOP ", "
837 which cannot be caught or ignored.
838 .SH CONFORMING TO
839 POSIX.1-2001, POSIX.1-2008, SVr4.
840 .\" SVr4 does not document the EINTR condition.
841 .SH NOTES
842 A child created via
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.
850 According to POSIX, the behavior of a process is undefined after it
851 ignores a
852 .BR SIGFPE ,
853 .BR SIGILL ,
854 or
855 .B SIGSEGV
856 signal that was not generated by
857 .BR kill (2)
858 or
859 .BR raise (3).
860 Integer division by zero has undefined result.
861 On some architectures it will generate a
862 .B SIGFPE
863 signal.
864 (Also dividing the most negative integer by \-1 may generate
865 .BR SIGFPE .)
866 Ignoring this signal might lead to an endless loop.
867 .PP
868 POSIX.1-1990 disallowed setting the action for
869 .B SIGCHLD
870 to
871 .BR SIG_IGN .
872 POSIX.1-2001 and later allow this possibility, so that ignoring
873 .B SIGCHLD
874 can be used to prevent the creation of zombies (see
875 .BR wait (2)).
876 Nevertheless, the historical BSD and System\ V behaviors for ignoring
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.
884 .PP
885 POSIX.1-1990 specified only
886 .BR SA_NOCLDSTOP .
887 POSIX.1-2001 added
888 .BR SA_NOCLDSTOP ,
889 .BR SA_NOCLDWAIT ,
890 .BR SA_NODEFER ,
891 .BR SA_ONSTACK ,
892 .BR SA_RESETHAND ,
893 .BR SA_RESTART ,
894 and
895 .BR SA_SIGINFO .
896 Use of these latter values in
897 .I sa_flags
898 may be less portable in applications intended for older
899 UNIX implementations.
900 .PP
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
908 1.3.9 and newer.
909 On older kernels the Linux implementation
910 allowed the receipt of any signal, not just the one we are installing
911 (effectively overriding any
912 .I sa_mask
913 settings).
914 .PP
915 .BR sigaction ()
916 can be called with a NULL second argument to query the current signal
917 handler.
918 It can also be used to check whether a given signal is valid for
919 the current machine by calling it with NULL second and third arguments.
920 .PP
921 It is not possible to block
922 .BR SIGKILL " or " SIGSTOP
923 (by specifying them in
924 .IR sa_mask ).
925 Attempts to do so are silently ignored.
926 .PP
927 See
928 .BR sigsetops (3)
929 for details on manipulating signal sets.
930 .PP
931 See
932 .BR signal-safety (7)
933 for a list of the async-signal-safe functions that can be
934 safely called inside from inside a signal handler.
935 .\"
936 .SS C library/kernel differences
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.
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 .\"
975 .SS Undocumented
976 Before the introduction of
977 .BR SA_SIGINFO ,
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".
983 See the relevant Linux kernel sources for details.
984 This use is obsolete now.
985 .SH BUGS
986 In kernels up to and including 2.6.13, specifying
987 .B SA_NODEFER
988 in
989 .I sa_flags
990 prevents not only the delivered signal from being masked during
991 execution of the handler, but also the signals specified in
992 .IR sa_mask .
993 This bug was fixed in kernel 2.6.14.
994 .SH EXAMPLE
995 See
996 .BR mprotect (2).
997 .SH SEE ALSO
998 .BR kill (1),
999 .BR kill (2),
1000 .BR pause (2),
1001 .BR restart_syscall (2),
1002 .BR seccomp (2)
1003 .BR sigaltstack (2),
1004 .BR signal (2),
1005 .BR signalfd (2),
1006 .BR sigpending (2),
1007 .BR sigprocmask (2),
1008 .BR sigreturn (2),
1009 .BR sigsuspend (2),
1010 .BR wait (2),
1011 .BR killpg (3),
1012 .BR raise (3),
1013 .BR siginterrupt (3),
1014 .BR sigqueue (3),
1015 .BR sigsetops (3),
1016 .BR sigvec (3),
1017 .BR core (5),
1018 .BR signal (7)