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