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 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" Since the Linux kernel and libraries are constantly changing, this
  16 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  17 .\" responsibility for errors or omissions, or for damages resulting from
  18 .\" the use of the information contained herein.  The author(s) may not
  19 .\" have taken the same level of care in the production of this manual,
  20 .\" which is licensed free of charge, as they might when working
  21 .\" professionally.
  22 .\"
  23 .\" Formatted or processed versions of this manual, if unaccompanied by
  24 .\" the source, must acknowledge the copyright and authors of this work.
  25 .\"
  26 .\" Modified, aeb, 960424
  27 .\" Modified Fri Jan 31 17:31:20 1997 by Eric S. Raymond <esr@thyrsus.com>
  28 .\" Modified Thu Nov 26 02:12:45 1998 by aeb - add SIGCHLD stuff.
  29 .\" Modified Sat May  8 17:40:19 1999 by Matthew Wilcox
  30 .\"     add POSIX.1b signals
  31 .\" Modified Sat Dec 29 01:44:52 2001 by Evan Jones <ejones@uwaterloo.ca>
  32 .\"     SA_ONSTACK
  33 .\" Modified 2004-11-11 by Michael Kerrisk <mtk.manpages@gmail.com>
  34 .\"     Added mention of SIGCONT under SA_NOCLDSTOP
  35 .\"     Added SA_NOCLDWAIT
  36 .\" Modified 2004-11-17 by Michael Kerrisk <mtk.manpages@gmail.com>
  37 .\"     Updated discussion for POSIX.1-2001 and SIGCHLD and sa_flags.
  38 .\"     Formatting fixes
  39 .\" 2004-12-09, mtk, added SI_TKILL + other minor changes
  40 .\" 2005-09-15, mtk, split sigpending(), sigprocmask(), sigsuspend()
  41 .\"     out of this page into separate pages.
  42 .\"
  43 .TH SIGACTION 2 2005-07-08 "Linux" "Linux Programmer's Manual"
  44 .SH NAME
  45 sigaction \- examine and change a signal action
  46 .SH SYNOPSIS
  47 .nf
  48 .B #include <signal.h>
  49 .sp
  50 .BI "int sigaction(int " signum ", const struct sigaction *" act ,
  51 .BI "              struct sigaction *" oldact );
  52 .fi
  53 .SH DESCRIPTION
  54 The
  55 .BR sigaction ()
  56 system call is used to change the action taken by a process on
  57 receipt of a specific signal.
  58 .PP
  59 .I signum
  60 specifies the signal and can be any valid signal except
  61 .B SIGKILL
  62 and
  63 .BR SIGSTOP .
  64 .PP
  65 If
  66 .I act
  67 is non\-null, the new action for signal
  68 .I signum
  69 is installed from
  70 .IR act .
  71 If
  72 .I oldact
  73 is non\-null, the previous action is saved in
  74 .IR oldact .
  75 .PP
  76 The
  77 .I sigaction
  78 structure is defined as something like
  79 .sp
  80 .RS
  81 .nf
  82 struct sigaction {
  83     void     (*sa_handler)(int);
  84     void     (*sa_sigaction)(int, siginfo_t *, void *);
  85     sigset_t   sa_mask;
  86     int        sa_flags;
  87     void     (*sa_restorer)(void);
  88 }
  89 .fi
  90 .RE
  91 .PP
  92 On some architectures a union is involved: do not assign to both
  93 .I sa_handler
  94 and
  95 .IR sa_sigaction .
  96 .PP
  97 The
  98 .I sa_restorer
  99 element is obsolete and should not be used.
 100 POSIX does not specify a
 101 .I sa_restorer
 102 element.
 103 .PP
 104 .I sa_handler
 105 specifies the action to be associated with
 106 .I signum
 107 and may be
 108 .B SIG_DFL
 109 for the default action,
 110 .B SIG_IGN
 111 to ignore this signal, or a pointer to a signal handling function.
 112 This function receives the signal number as its only argument.
 113 .PP
 114 If
 115 .B SA_SIGINFO
 116 is specified in
 117 .IR sa_flags ,
 118 then
 119 .I sa_sigaction
 120 (instead of
 121 .IR sa_handler )
 122 specifies the signal-handling function for
 123 .IR signum .
 124 This function receives the signal number as its first argument, a
 125 pointer to a
 126 .I siginfo_t
 127 as its second argument and a pointer to a
 128 .I ucontext_t
 129 (cast to void *) as its third argument.
 130 .PP
 131 .I sa_mask
 132 gives a mask of signals which should be blocked during execution of
 133 the signal handler.
 134 In addition, the signal which triggered the handler
 135 will be blocked, unless the
 136 .B SA_NODEFER
 137 flag is used.
 138 .PP
 139 .I sa_flags
 140 specifies a set of flags which modify the behavior of the signal handling
 141 process.
 142 It is formed by the bitwise OR of zero or more of the following:
 143 .RS
 144 .TP
 145 .B SA_NOCLDSTOP
 146 If
 147 .I signum
 148 is
 149 .BR SIGCHLD ,
 150 do not receive notification when child processes stop (i.e., when they
 151 receive one of
 152 .BR SIGSTOP ", " SIGTSTP ", " SIGTTIN
 153 or
 154 .BR SIGTTOU )
 155 or resume (i.e., they receive
 156 .BR SIGCONT )
 157 (see
 158 .BR wait (2)).
 159 .TP
 160 .B SA_NOCLDWAIT
 161 (Linux 2.6 and later)
 162 .\" To be precise: Linux 2.5.60 -- MTK
 163 If
 164 .I signum
 165 is
 166 .BR SIGCHLD ,
 167 do not transform children into zombies when they terminate.
 168 See also
 169 .BR waitpid (2).
 170 .TP
 171 .B SA_RESETHAND
 172 Restore the signal action to the default state once the signal handler
 173 has been called.
 174 .B SA_ONESHOT
 175 is an obsolete, non-standard synonym for this flag.
 176 .TP
 177 .BR SA_ONSTACK
 178 Call the signal handler on an alternate signal stack provided by
 179 .BR sigaltstack (2).
 180 If an alternate stack is not available, the default stack will be used.
 181 .TP
 182 .B SA_RESTART
 183 Provide behavior compatible with BSD signal semantics by making certain
 184 system calls restartable across signals.
 185 .TP
 186 .B SA_NODEFER
 187 Do not prevent the signal from being received from within its own signal
 188 handler.
 189 .B SA_NOMASK
 190 is an obsolete, non-standard synonym for this flag.
 191 .TP
 192 .B SA_SIGINFO
 193 The signal handler takes 3 arguments, not one.
 194 In this case,
 195 .I sa_sigaction
 196 should be set instead of
 197 .IR sa_handler .
 198 (The
 199 .I sa_sigaction
 200 field was added in Linux 2.1.86.)
 201 .RE
 202 .PP
 203 The
 204 .I siginfo_t
 205 parameter to
 206 .I sa_sigaction
 207 is a struct with the following elements
 208 .sp
 209 .RS
 210 .nf
 211 siginfo_t {
 212 .\" FIXME si_tid and si_overrun are not documented.
 213 .\" FIXME si_trapno is not documented; is it actually used?
 214     int      si_signo;    /* Signal number */
 215     int      si_errno;    /* An errno value */
 216     int      si_code;     /* Signal code */
 217     pid_t    si_pid;      /* Sending process ID */
 218     uid_t    si_uid;      /* Real user ID of sending process */
 219     int      si_status;   /* Exit value or signal */
 220     clock_t  si_utime;    /* User time consumed */
 221     clock_t  si_stime;    /* System time consumed */
 222     sigval_t si_value;    /* Signal value */
 223     int      si_int;      /* POSIX.1b signal */
 224     void    *si_ptr;      /* POSIX.1b signal */
 225     void    *si_addr;     /* Memory location which caused fault */
 226     int      si_band;     /* Band event */
 227     int      si_fd;       /* File descriptor */
 228 }
 229 .fi
 230 .RE
 231
 232 .IR si_signo ", " si_errno " and " si_code
 233 are defined for all signals.
 234 .RI ( si_errno
 235 is unused on Linux.)
 236 The rest of the struct may be a union, so that one should only
 237 read the fields that are meaningful for the given signal:
 238 .IP * 2
 239 POSIX.1b signals and
 240 .B SIGCHLD
 241 fill in
 242 .IR si_pid " and " si_uid .
 243 .BR
 244 .IP *
 245 .B SIGCHLD
 246 also fills in
 247 .IR si_status ", " si_utime " and " si_stime .
 248 .IP *
 249 .IR si_int " and " si_ptr
 250 are specified by the sender of the POSIX.1b signal.
 251 See
 252 .BR sigqueue (2)
 253 for more details.
 254 .IP *
 255 .BR SIGILL ,
 256 .BR SIGFPE ,
 257 .BR SIGSEGV ,
 258 and
 259 .B SIGBUS
 260 fill in
 261 .I si_addr
 262 with the address of the fault.
 263 .B SIGPOLL
 264 fills in
 265 .IR si_band " and " si_fd .
 266 .PP
 267 .I si_code
 268 is a value (not a bit mask)
 269 indicating why this signal was sent.
 270 The following list shows the values can be placed in
 271 .I si_code
 272 for any signal, along with reason that the signal was generated.
 273 .RS 4
 274 .TP 15
 275 .B SI_USER
 276 .BR kill (2)
 277 or
 278 .BR raise (3)
 279 .TP
 280 .B SI_KERNEL
 281 Sent by the kernel.
 282 .TP
 283 .B SI_QUEUE
 284 .BR sigqueue (2)
 285 .TP
 286 .B SI_TIMER
 287 POSIX timer expired
 288 .TP
 289 .B SI_MESGQ
 290 POSIX message queue state changed (since Linux 2.6.6); see
 291 .BR mq_notify (3)
 292 .TP
 293 .B SI_ASYNCIO
 294 AIO completed
 295 .TP
 296 .B SI_SIGIO
 297 queued SIGIO
 298 .TP
 299 .B SI_TKILL
 300 .BR tkill (2)
 301 or
 302 .BR tgkill (2)
 303 (since Linux 2.4.19)
 304 .\" SI_DETHREAD is defined in 2.6.9 sources, but isn't implemented
 305 .\" It appears to have been an idea that was tried during 2.5.6
 306 .\" through to 2.5.24 and then was backed out.
 307 .RE
 308 .PP
 309 The following values can be place in
 310 .I si_code
 311 for a
 312 .B SIGILL
 313 signal:
 314 .RS 4
 315 .TP 15
 316 .B ILL_ILLOPC
 317 illegal opcode
 318 .TP
 319 .B ILL_ILLOPN
 320 illegal operand
 321 .TP
 322 .B ILL_ILLADR
 323 illegal addressing mode
 324 .TP
 325 .B ILL_ILLTRP
 326 illegal trap
 327 .TP
 328 .B ILL_PRVOPC
 329 privileged opcode
 330 .TP
 331 .B ILL_PRVREG
 332 privileged register
 333 .TP
 334 .B ILL_COPROC
 335 coprocessor error
 336 .TP
 337 .B ILL_BADSTK
 338 internal stack error
 339 .RE
 340 .PP
 341 The following values can be place in
 342 .I si_code
 343 for a
 344 .B SIGFPE
 345 signal:
 346 .RS 4
 347 .TP 15
 348 .B FPE_INTDIV
 349 integer divide by zero
 350 .TP
 351 .B FPE_INTOVF
 352 integer overflow
 353 .TP
 354 .B FPE_FLTDIV
 355 floating point divide by zero
 356 .TP
 357 .B FPE_FLTOVF
 358 floating point overflow
 359 .TP
 360 .B FPE_FLTUND
 361 floating point underflow
 362 .TP
 363 .B FPE_FLTRES
 364 floating point inexact result
 365 .TP
 366 .B FPE_FLTINV
 367 floating point invalid operation
 368 .TP
 369 .B FPE_FLTSUB
 370 subscript out of range
 371 .RE
 372 .PP
 373 The following values can be place in
 374 .I si_code
 375 for a
 376 .B SIGSEGV
 377 signal:
 378 .RS 4
 379 .TP 15
 380 .B SEGV_MAPERR
 381 address not mapped to object
 382 .TP
 383 .B SEGV_ACCERR
 384 invalid permissions for mapped object
 385 .RE
 386 .PP
 387 The following values can be place in
 388 .I si_code
 389 for a
 390 .B SIGBUS
 391 signal:
 392 .RS 4
 393 .TP 15
 394 .B BUS_ADRALN
 395 invalid address alignment
 396 .TP
 397 .B BUS_ADRERR
 398 non-existent physical address
 399 .TP
 400 .B BUS_OBJERR
 401 object specific hardware error
 402 .RE
 403 .PP
 404 The following values can be place in
 405 .I si_code
 406 for a
 407 .B SIGTRAP
 408 signal:
 409 .RS 4
 410 .TP 15
 411 .B TRAP_BRKPT
 412 process breakpoint
 413 .TP
 414 .B TRAP_TRACE
 415 process trace trap
 416 .RE
 417 .PP
 418 The following values can be place in
 419 .I si_code
 420 for a
 421 .B SIGCHLD
 422 signal:
 423 .RS 4
 424 .TP 15
 425 .B CLD_EXITED
 426 child has exited
 427 .TP
 428 .B CLD_KILLED
 429 child was killed
 430 .TP
 431 .B CLD_DUMPED
 432 child terminated abnormally
 433 .TP
 434 .B CLD_TRAPPED
 435 traced child has trapped
 436 .TP
 437 .B CLD_STOPPED
 438 child has stopped
 439 .TP
 440 .B CLD_CONTINUED
 441 stopped child has continued (since Linux 2.6.9)
 442 .RE
 443 .PP
 444 The following values can be place in
 445 .I si_code
 446 for a
 447 .B SIGPOLL
 448 signal:
 449 .RS 4
 450 .TP 15
 451 .B POLL_IN
 452 data input available
 453 .TP
 454 .B POLL_OUT
 455 output buffers available
 456 .TP
 457 .B POLL_MSG
 458 input message available
 459 .TP
 460 .B POLL_ERR
 461 i/o error
 462 .TP
 463 .B POLL_PRI
 464 high priority input available
 465 .TP
 466 .B POLL_HUP
 467 device disconnected
 468 .RE
 469 .SH "RETURN VALUE"
 470 .BR sigaction ()
 471 returns 0 on success and \-1 on error.
 472 .SH ERRORS
 473 .TP
 474 .B EFAULT
 475 .IR act " or " oldact
 476 points to memory which is not a valid part of the process address space.
 477 .TP
 478 .B EINVAL
 479 An invalid signal was specified.
 480 This will also be generated if an attempt
 481 is made to change the action for
 482 .BR SIGKILL " or " SIGSTOP ", "
 483 which cannot be caught or ignored.
 484 .SH "CONFORMING TO"
 485 POSIX.1-2001, SVr4.
 486 .\" SVr4 does not document the EINTR condition.
 487 .SH NOTES
 488 .PP
 489 According to POSIX, the behavior of a process is undefined after it
 490 ignores a
 491 .BR SIGFPE ,
 492 .BR SIGILL ,
 493 or
 494 .BR SIGSEGV
 495 signal that was not generated by
 496 .BR kill (2)
 497 or
 498 .BR raise (3).
 499 Integer division by zero has undefined result.
 500 On some architectures it will generate a
 501 .B SIGFPE
 502 signal.
 503 (Also dividing the most negative integer by \-1 may generate
 504 .BR SIGFPE .)
 505 Ignoring this signal might lead to an endless loop.
 506 .PP
 507 POSIX.1-1990 disallowed setting the action for
 508 .B SIGCHLD
 509 to
 510 .BR SIG_IGN .
 511 POSIX.1-2001 allows this possibility, so that ignoring
 512 .B SIGCHLD
 513 can be used to prevent the creation of zombies (see
 514 .BR wait (2)).
 515 Nevertheless, the historical BSD and System V behaviors for ignoring
 516 .B SIGCHLD
 517 differ, so that the only completely portable method of ensuring that
 518 terminated children do not become zombies is to catch the
 519 .B SIGCHLD
 520 signal and perform a
 521 .BR wait (2)
 522 or similar.
 523 .PP
 524 POSIX.1-1990 only specified
 525 .BR SA_NOCLDSTOP .
 526 POSIX.1-2001 added
 527 .BR SA_NOCLDWAIT ,
 528 .BR SA_RESETHAND ,
 529 .BR SA_NODEFER ,
 530 and
 531 .BR SA_SIGINFO .
 532 Use of these latter values in
 533 .I sa_flags
 534 may be less portable in applications intended for older
 535 Unix implementations.
 536 .PP
 537 Support for
 538 .B SA_SIGINFO
 539 was added in Linux 2.2.
 540 .PP
 541 The
 542 .B SA_RESETHAND
 543 flag is compatible with the SVr4 flag of the same name.
 544 .PP
 545 The
 546 .B SA_NODEFER
 547 flag is compatible with the SVr4 flag of the same name under kernels
 548 1.3.9 and newer.
 549 On older kernels the Linux implementation
 550 allowed the receipt of any signal, not just the one we are installing
 551 (effectively overriding any
 552 .I sa_mask
 553 settings).
 554 .\".PP
 555 .\"The
 556 .\".BR SA_RESETHAND " and " SA_NODEFER
 557 .\"names for SVr4 compatibility are present only in library versions 3.0.9
 558 .\"and greater.
 559 .PP
 560 .BR sigaction ()
 561 can be called with a null second argument to query the current signal
 562 handler.
 563 It can also be used to check whether a given signal is valid for
 564 the current machine by calling it with null second and third arguments.
 565 .PP
 566 It is not possible to block
 567 .BR SIGKILL " or " SIGSTOP
 568 (by specifying them in
 569 .IR sa_mask ).
 570 Attempts to do so are silently ignored.
 571 .PP
 572 See
 573 .BR sigsetops (3)
 574 for details on manipulating signal sets.
 575 .PP
 576 See
 577 .BR signal (7)
 578 for a list of the async-signal-safe functions that can be
 579 safely called inside from inside a signal handler.
 580 .SS Undocumented
 581 Before the introduction of
 582 .B SA_SIGINFO
 583 it was also possible to get some additional information,
 584 namely by using a
 585 .I sa_handler
 586 with second argument of type
 587 .IR "struct sigcontext".
 588 See the relevant kernel sources for details.
 589 This use is obsolete now.
 590 .SH BUGS
 591 In kernels up to and including 2.6.13, specifying
 592 .B SA_NODEFER
 593 in
 594 .I sa_flags
 595 prevents not only the delivered signal from being masked during
 596 execution of the handler, but also the signals specified in
 597 .IR sa_mask .
 598 This bug was fixed in kernel 2.6.14.
 599 .SH EXAMPLE
 600 See
 601 .BR mprotect (2).
 602 .SH "SEE ALSO"
 603 .BR kill (1),
 604 .BR kill (2),
 605 .BR killpg (2),
 606 .BR pause (2),
 607 .BR sigaltstack (2),
 608 .BR signal (2),
 609 .BR sigpending (2),
 610 .BR sigprocmask (2),
 611 .BR sigqueue (2),
 612 .BR sigsuspend (2),
 613 .BR wait (2),
 614 .BR raise (3),
 615 .BR siginterrupt (3),
 616 .BR sigsetops (3),
 617 .BR sigvec (3),
 618 .BR core (5),
 619 .BR signal (7)