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