original/man2/sigaction.2

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