lib/libc/sys/sigaction.2

   1 .\" Copyright (c) 1980, 1990, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 4. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .\"     From: @(#)sigaction.2   8.2 (Berkeley) 4/3/94
  29 .\" $FreeBSD$
  30 .\"
  31 .Dd September 6, 2013
  32 .Dt SIGACTION 2
  33 .Os
  34 .Sh NAME
  35 .Nm sigaction
  36 .Nd software signal facilities
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In signal.h
  41 .Bd -literal
  42 struct  sigaction {
  43         void    (*sa_handler)(int);
  44         void    (*sa_sigaction)(int, siginfo_t *, void *);
  45         int     sa_flags;               /* see signal options below */
  46         sigset_t sa_mask;               /* signal mask to apply */
  47 };
  48 .Ed
  49 .Ft int
  50 .Fo sigaction
  51 .Fa "int sig"
  52 .Fa "const struct sigaction * restrict act"
  53 .Fa "struct sigaction * restrict oact"
  54 .Fc
  55 .Sh DESCRIPTION
  56 The system defines a set of signals that may be delivered to a process.
  57 Signal delivery resembles the occurrence of a hardware interrupt:
  58 the signal is normally blocked from further occurrence, the current thread
  59 context is saved, and a new one is built.
  60 A process may specify a
  61 .Em handler
  62 to which a signal is delivered, or specify that a signal is to be
  63 .Em ignored .
  64 A process may also specify that a default action is to be taken
  65 by the system when a signal occurs.
  66 A signal may also be
  67 .Em blocked
  68 for a thread,
  69 in which case it will not be delivered to that thread until it is
  70 .Em unblocked .
  71 The action to be taken on delivery is determined at the time
  72 of delivery.
  73 Normally, signal handlers execute on the current stack
  74 of the thread.
  75 This may be changed, on a per-handler basis,
  76 so that signals are taken on a special
  77 .Em "signal stack" .
  78 .Pp
  79 Signal routines normally execute with the signal that caused their
  80 invocation
  81 .Em blocked ,
  82 but other signals may yet occur.
  83 A global
  84 .Em "signal mask"
  85 defines the set of signals currently blocked from delivery
  86 to a thread.
  87 The signal mask for a thread is initialized
  88 from that of its parent (normally empty).
  89 It may be changed with a
  90 .Xr sigprocmask 2
  91 or
  92 .Xr pthread_sigmask 3
  93 call, or when a signal is delivered to the thread.
  94 .Pp
  95 When a signal
  96 condition arises for a process or thread, the signal is added to a set of
  97 signals pending for the process or thread.
  98 Whether the signal is directed at the process in general or at a specific
  99 thread depends on how it is generated.
 100 For signals directed at a specific thread,
 101 if the signal is not currently
 102 .Em blocked
 103 by the thread then it is delivered to the thread.
 104 For signals directed at the process,
 105 if the signal is not currently
 106 .Em blocked
 107 by all threads then it is delivered to one thread that does not have it blocked
 108 (the selection of which is unspecified).
 109 Signals may be delivered any time a thread enters the operating system
 110 (e.g., during a system call, page fault or trap, or clock interrupt).
 111 If multiple signals are ready to be delivered at the same time,
 112 any signals that could be caused by traps are delivered first.
 113 Additional signals may be processed at the same time, with each
 114 appearing to interrupt the handlers for the previous signals
 115 before their first instructions.
 116 The set of pending signals is returned by the
 117 .Xr sigpending 2
 118 system call.
 119 When a caught signal
 120 is delivered, the current state of the thread is saved,
 121 a new signal mask is calculated (as described below),
 122 and the signal handler is invoked.
 123 The call to the handler
 124 is arranged so that if the signal handling routine returns
 125 normally the thread will resume execution in the context
 126 from before the signal's delivery.
 127 If the thread wishes to resume in a different context, then it
 128 must arrange to restore the previous context itself.
 129 .Pp
 130 When a signal is delivered to a thread a new signal mask is
 131 installed for the duration of the process' signal handler
 132 (or until a
 133 .Xr sigprocmask 2
 134 system call is made).
 135 This mask is formed by taking the union of the current signal mask set,
 136 the signal to be delivered, and
 137 the signal mask associated with the handler to be invoked.
 138 .Pp
 139 The
 140 .Fn sigaction
 141 system call
 142 assigns an action for a signal specified by
 143 .Fa sig .
 144 If
 145 .Fa act
 146 is non-zero, it
 147 specifies an action
 148 .Dv ( SIG_DFL ,
 149 .Dv SIG_IGN ,
 150 or a handler routine) and mask
 151 to be used when delivering the specified signal.
 152 If
 153 .Fa oact
 154 is non-zero, the previous handling information for the signal
 155 is returned to the user.
 156 .Pp
 157 The above declaration of
 158 .Vt "struct sigaction"
 159 is not literal.
 160 It is provided only to list the accessible members.
 161 See
 162 .In sys/signal.h
 163 for the actual definition.
 164 In particular, the storage occupied by sa_handler and sa_sigaction overlaps,
 165 and an application can not use both simultaneously.
 166 .Pp
 167 Once a signal handler is installed, it normally remains installed
 168 until another
 169 .Fn sigaction
 170 system call is made, or an
 171 .Xr execve 2
 172 is performed.
 173 A signal-specific default action may be reset by
 174 setting
 175 .Va sa_handler
 176 to
 177 .Dv SIG_DFL .
 178 The defaults are process termination, possibly with core dump;
 179 no action; stopping the process; or continuing the process.
 180 See the signal list below for each signal's default action.
 181 If
 182 .Va sa_handler
 183 is
 184 .Dv SIG_DFL ,
 185 the default action for the signal is to discard the signal,
 186 and if a signal is pending,
 187 the pending signal is discarded even if the signal is masked.
 188 If
 189 .Va sa_handler
 190 is set to
 191 .Dv SIG_IGN
 192 current and pending instances
 193 of the signal are ignored and discarded.
 194 .Pp
 195 Options may be specified by setting
 196 .Va sa_flags .
 197 The meaning of the various bits is as follows:
 198 .Bl -tag -offset indent -width SA_RESETHANDXX
 199 .It Dv SA_NOCLDSTOP
 200 If this bit is set when installing a catching function
 201 for the
 202 .Dv SIGCHLD
 203 signal,
 204 the
 205 .Dv SIGCHLD
 206 signal will be generated only when a child process exits,
 207 not when a child process stops.
 208 .It Dv SA_NOCLDWAIT
 209 If this bit is set when calling
 210 .Fn sigaction
 211 for the
 212 .Dv SIGCHLD
 213 signal, the system will not create zombie processes when children of
 214 the calling process exit.
 215 If the calling process subsequently issues a
 216 .Xr wait 2
 217 (or equivalent), it blocks until all of the calling process's child
 218 processes terminate, and then returns a value of \-1 with
 219 .Va errno
 220 set to
 221 .Er ECHILD .
 222 The same effect of avoiding zombie creation can also be achieved by setting
 223 .Va sa_handler
 224 for
 225 .Dv SIGCHLD
 226 to
 227 .Dv SIG_IGN .
 228 .It Dv SA_ONSTACK
 229 If this bit is set, the system will deliver the signal to the process
 230 on a
 231 .Em "signal stack" ,
 232 specified by each thread with
 233 .Xr sigaltstack 2 .
 234 .It Dv SA_NODEFER
 235 If this bit is set, further occurrences of the delivered signal are
 236 not masked during the execution of the handler.
 237 .It Dv SA_RESETHAND
 238 If this bit is set, the handler is reset back to
 239 .Dv SIG_DFL
 240 at the moment the signal is delivered.
 241 .It Dv SA_RESTART
 242 See paragraph below.
 243 .It Dv SA_SIGINFO
 244 If this bit is set, the handler function is assumed to be pointed to by the
 245 .Va sa_sigaction
 246 member of
 247 .Vt "struct sigaction"
 248 and should match the prototype shown above or as below in
 249 .Sx EXAMPLES .
 250 This bit should not be set when assigning
 251 .Dv SIG_DFL
 252 or
 253 .Dv SIG_IGN .
 254 .El
 255 .Pp
 256 If a signal is caught during the system calls listed below,
 257 the call may be forced to terminate
 258 with the error
 259 .Er EINTR ,
 260 the call may return with a data transfer shorter than requested,
 261 or the call may be restarted.
 262 Restart of pending calls is requested
 263 by setting the
 264 .Dv SA_RESTART
 265 bit in
 266 .Va sa_flags .
 267 The affected system calls include
 268 .Xr open 2 ,
 269 .Xr read 2 ,
 270 .Xr write 2 ,
 271 .Xr sendto 2 ,
 272 .Xr recvfrom 2 ,
 273 .Xr sendmsg 2
 274 and
 275 .Xr recvmsg 2
 276 on a communications channel or a slow device (such as a terminal,
 277 but not a regular file)
 278 and during a
 279 .Xr wait 2
 280 or
 281 .Xr ioctl 2 .
 282 However, calls that have already committed are not restarted,
 283 but instead return a partial success (for example, a short read count).
 284 .Pp
 285 After a
 286 .Xr pthread_create 3
 287 the signal mask is inherited by the new thread and
 288 the set of pending signals and the signal stack for the new thread are empty.
 289 .Pp
 290 After a
 291 .Xr fork 2
 292 or
 293 .Xr vfork 2
 294 all signals, the signal mask, the signal stack,
 295 and the restart/interrupt flags are inherited by the child.
 296 .Pp
 297 The
 298 .Xr execve 2
 299 system call reinstates the default
 300 action for all signals which were caught and
 301 resets all signals to be caught on the user stack.
 302 Ignored signals remain ignored;
 303 the signal mask remains the same;
 304 signals that restart pending system calls continue to do so.
 305 .Pp
 306 The following is a list of all signals
 307 with names as in the include file
 308 .In signal.h :
 309 .Bl -column SIGVTALARMXX "create core imagexxx"
 310 .It Sy "NAME    Default Action  Description"
 311 .It Dv SIGHUP No "      terminate process" "    terminal line hangup"
 312 .It Dv SIGINT No "      terminate process" "    interrupt program"
 313 .It Dv SIGQUIT No "     create core image" "    quit program"
 314 .It Dv SIGILL No "      create core image" "    illegal instruction"
 315 .It Dv SIGTRAP No "     create core image" "    trace trap"
 316 .It Dv SIGABRT No "     create core image" Ta Xr abort 3
 317 call (formerly
 318 .Dv SIGIOT )
 319 .It Dv SIGEMT No "      create core image" "    emulate instruction executed"
 320 .It Dv SIGFPE No "      create core image" "    floating-point exception"
 321 .It Dv SIGKILL No "     terminate process" "    kill program"
 322 .It Dv SIGBUS No "      create core image" "    bus error"
 323 .It Dv SIGSEGV No "     create core image" "    segmentation violation"
 324 .It Dv SIGSYS No "      create core image" "    non-existent system call invoked"
 325 .It Dv SIGPIPE No "     terminate process" "    write on a pipe with no reader"
 326 .It Dv SIGALRM No "     terminate process" "    real-time timer expired"
 327 .It Dv SIGTERM No "     terminate process" "    software termination signal"
 328 .It Dv SIGURG No "      discard signal" "       urgent condition present on socket"
 329 .It Dv SIGSTOP No "     stop process" " stop (cannot be caught or ignored)"
 330 .It Dv SIGTSTP No "     stop process" " stop signal generated from keyboard"
 331 .It Dv SIGCONT No "     discard signal" "       continue after stop"
 332 .It Dv SIGCHLD No "     discard signal" "       child status has changed"
 333 .It Dv SIGTTIN No "     stop process" " background read attempted from control terminal"
 334 .It Dv SIGTTOU No "     stop process" " background write attempted to control terminal"
 335 .It Dv SIGIO No "       discard signal" Tn "    I/O"
 336 is possible on a descriptor (see
 337 .Xr fcntl 2 )
 338 .It Dv SIGXCPU No "     terminate process" "    cpu time limit exceeded (see"
 339 .Xr setrlimit 2 )
 340 .It Dv SIGXFSZ No "     terminate process" "    file size limit exceeded (see"
 341 .Xr setrlimit 2 )
 342 .It Dv SIGVTALRM No "   terminate process" "    virtual time alarm (see"
 343 .Xr setitimer 2 )
 344 .It Dv SIGPROF No "     terminate process" "    profiling timer alarm (see"
 345 .Xr setitimer 2 )
 346 .It Dv SIGWINCH No "    discard signal" "       Window size change"
 347 .It Dv SIGINFO No "     discard signal" "       status request from keyboard"
 348 .It Dv SIGUSR1 No "     terminate process" "    User defined signal 1"
 349 .It Dv SIGUSR2 No "     terminate process" "    User defined signal 2"
 350 .El
 351 .Sh NOTE
 352 The
 353 .Va sa_mask
 354 field specified in
 355 .Fa act
 356 is not allowed to block
 357 .Dv SIGKILL
 358 or
 359 .Dv SIGSTOP .
 360 Any attempt to do so will be silently ignored.
 361 .Pp
 362 The following functions are either reentrant or not interruptible
 363 by signals and are async-signal safe.
 364 Therefore applications may
 365 invoke them, without restriction, from signal-catching functions
 366 or from a child process after calling
 367 .Xr fork 2
 368 in a multi-threaded process:
 369 .Pp
 370 Base Interfaces:
 371 .Pp
 372 .Fn _Exit ,
 373 .Fn _exit ,
 374 .Fn accept ,
 375 .Fn access ,
 376 .Fn alarm ,
 377 .Fn bind ,
 378 .Fn cfgetispeed ,
 379 .Fn cfgetospeed ,
 380 .Fn cfsetispeed ,
 381 .Fn cfsetospeed ,
 382 .Fn chdir ,
 383 .Fn chmod ,
 384 .Fn chown ,
 385 .Fn close ,
 386 .Fn connect ,
 387 .Fn creat ,
 388 .Fn dup ,
 389 .Fn dup2 ,
 390 .Fn execl ,
 391 .Fn execle ,
 392 .Fn execv ,
 393 .Fn execve ,
 394 .Fn faccessat ,
 395 .Fn fchdir ,
 396 .Fn fchmod ,
 397 .Fn fchmodat ,
 398 .Fn fchown ,
 399 .Fn fchownat ,
 400 .Fn fcntl ,
 401 .Fn fork ,
 402 .Fn fstat ,
 403 .Fn fstatat ,
 404 .Fn fsync ,
 405 .Fn ftruncate ,
 406 .Fn getegid ,
 407 .Fn geteuid ,
 408 .Fn getgid ,
 409 .Fn getgroups ,
 410 .Fn getpeername ,
 411 .Fn getpgrp ,
 412 .Fn getpid ,
 413 .Fn getppid ,
 414 .Fn getsockname ,
 415 .Fn getsockopt ,
 416 .Fn getuid ,
 417 .Fn kill ,
 418 .Fn link ,
 419 .Fn linkat ,
 420 .Fn listen ,
 421 .Fn lseek ,
 422 .Fn lstat ,
 423 .Fn mkdir ,
 424 .Fn mkdirat ,
 425 .Fn mkfifo ,
 426 .Fn mkfifoat ,
 427 .Fn mknod ,
 428 .Fn mknodat ,
 429 .Fn open ,
 430 .Fn openat ,
 431 .Fn pause ,
 432 .Fn pipe ,
 433 .Fn poll ,
 434 .Fn pselect ,
 435 .Fn pthread_sigmask ,
 436 .Fn raise ,
 437 .Fn read ,
 438 .Fn readlink ,
 439 .Fn readlinkat ,
 440 .Fn recv ,
 441 .Fn recvfrom ,
 442 .Fn recvmsg ,
 443 .Fn rename ,
 444 .Fn renameat ,
 445 .Fn rmdir ,
 446 .Fn select ,
 447 .Fn send ,
 448 .Fn sendmsg ,
 449 .Fn sendto ,
 450 .Fn setgid ,
 451 .Fn setpgid ,
 452 .Fn setsid ,
 453 .Fn setsockopt ,
 454 .Fn setuid ,
 455 .Fn shutdown ,
 456 .Fn sigaction ,
 457 .Fn sigaddset ,
 458 .Fn sigdelset ,
 459 .Fn sigemptyset ,
 460 .Fn sigfillset ,
 461 .Fn sigismember ,
 462 .Fn signal ,
 463 .Fn sigpending ,
 464 .Fn sigprocmask ,
 465 .Fn sigsuspend ,
 466 .Fn sleep ,
 467 .Fn sockatmark ,
 468 .Fn socket ,
 469 .Fn socketpair ,
 470 .Fn stat ,
 471 .Fn symlink ,
 472 .Fn symlinkat ,
 473 .Fn tcdrain ,
 474 .Fn tcflow ,
 475 .Fn tcflush ,
 476 .Fn tcgetattr ,
 477 .Fn tcgetpgrp ,
 478 .Fn tcsendbreak ,
 479 .Fn tcsetattr ,
 480 .Fn tcsetpgrp ,
 481 .Fn time ,
 482 .Fn times ,
 483 .Fn umask ,
 484 .Fn uname ,
 485 .Fn unlink ,
 486 .Fn unlinkat ,
 487 .Fn utime ,
 488 .Fn wait ,
 489 .Fn waitpid ,
 490 .Fn write .
 491 .Pp
 492 X/Open Systems Interfaces:
 493 .Pp
 494 .Fn sigpause ,
 495 .Fn sigset ,
 496 .Fn utimes .
 497 .Pp
 498 Realtime Interfaces:
 499 .Pp
 500 .Fn aio_error ,
 501 .Fn clock_gettime ,
 502 .Fn timer_getoverrun ,
 503 .Fn aio_return ,
 504 .Fn fdatasync ,
 505 .Fn sigqueue ,
 506 .Fn timer_gettime ,
 507 .Fn aio_suspend ,
 508 .Fn sem_post ,
 509 .Fn timer_settime .
 510 .Pp
 511 Base Interfaces not specified as async-signal safe by
 512 .Tn POSIX :
 513 .Pp
 514 .Fn fpathconf ,
 515 .Fn pathconf ,
 516 .Fn sysconf .
 517 .Pp
 518 Base Interfaces not specified as async-signal safe by
 519 .Tn POSIX ,
 520 but planned to be:
 521 .Pp
 522 .Fn ffs ,
 523 .Fn htonl ,
 524 .Fn htons ,
 525 .Fn memccpy ,
 526 .Fn memchr ,
 527 .Fn memcmp ,
 528 .Fn memcpy ,
 529 .Fn memmove ,
 530 .Fn memset ,
 531 .Fn ntohl ,
 532 .Fn ntohs ,
 533 .Fn stpcpy ,
 534 .Fn stpncpy ,
 535 .Fn strcat ,
 536 .Fn strchr ,
 537 .Fn strcmp ,
 538 .Fn strcpy ,
 539 .Fn strcspn ,
 540 .Fn strlen ,
 541 .Fn strncat ,
 542 .Fn strncmp ,
 543 .Fn strncpy ,
 544 .Fn strnlen ,
 545 .Fn strpbrk ,
 546 .Fn strrchr ,
 547 .Fn strspn ,
 548 .Fn strstr ,
 549 .Fn strtok_r ,
 550 .Fn wcpcpy ,
 551 .Fn wcpncpy ,
 552 .Fn wcscat ,
 553 .Fn wcschr ,
 554 .Fn wcscmp ,
 555 .Fn wcscpy ,
 556 .Fn wcscspn ,
 557 .Fn wcslen ,
 558 .Fn wcsncat ,
 559 .Fn wcsncmp ,
 560 .Fn wcsncpy ,
 561 .Fn wcsnlen ,
 562 .Fn wcspbrk ,
 563 .Fn wcsrchr ,
 564 .Fn wcsspn ,
 565 .Fn wcsstr ,
 566 .Fn wcstok ,
 567 .Fn wmemchr ,
 568 .Fn wmemcmp ,
 569 .Fn wmemcpy ,
 570 .Fn wmemmove ,
 571 .Fn wmemset .
 572 .Pp
 573 Extension Interfaces:
 574 .Pp
 575 .Fn accept4 ,
 576 .Fn bindat ,
 577 .Fn closefrom ,
 578 .Fn connectat ,
 579 .Fn eaccess ,
 580 .Fn ffsl ,
 581 .Fn ffsll ,
 582 .Fn flock ,
 583 .Fn fls ,
 584 .Fn flsl ,
 585 .Fn flsll ,
 586 .Fn futimesat ,
 587 .Fn pipe2 ,
 588 .Fn strlcat .
 589 .Fn strlcpy ,
 590 .Fn strsep .
 591 .Pp
 592 In addition, reading or writing
 593 .Va errno
 594 is async-signal safe.
 595 .Pp
 596 All functions not in the above lists are considered to be unsafe
 597 with respect to signals.
 598 That is to say, the behaviour of such
 599 functions is undefined when they are called from a signal handler
 600 that interrupted an unsafe function.
 601 In general though, signal handlers should do little more than set a
 602 flag; most other actions are not safe.
 603 .Pp
 604 Also, it is good practice to make a copy of the global variable
 605 .Va errno
 606 and restore it before returning from the signal handler.
 607 This protects against the side effect of
 608 .Va errno
 609 being set by functions called from inside the signal handler.
 610 .Sh RETURN VALUES
 611 .Rv -std sigaction
 612 .Sh EXAMPLES
 613 There are three possible prototypes the handler may match:
 614 .Bl -tag -offset indent -width short
 615 .It Tn ANSI C :
 616 .Ft void
 617 .Fn handler int ;
 618 .It Traditional BSD style:
 619 .Ft void
 620 .Fn handler int "int code" "struct sigcontext *scp" ;
 621 .It Tn POSIX Dv SA_SIGINFO :
 622 .Ft void
 623 .Fn handler int "siginfo_t *info" "ucontext_t *uap" ;
 624 .El
 625 .Pp
 626 The handler function should match the
 627 .Dv SA_SIGINFO
 628 prototype if the
 629 .Dv SA_SIGINFO
 630 bit is set in
 631 .Va sa_flags .
 632 It then should be pointed to by the
 633 .Va sa_sigaction
 634 member of
 635 .Vt "struct sigaction" .
 636 Note that you should not assign
 637 .Dv SIG_DFL
 638 or
 639 .Dv SIG_IGN
 640 this way.
 641 .Pp
 642 If the
 643 .Dv SA_SIGINFO
 644 flag is not set, the handler function should match
 645 either the
 646 .Tn ANSI C
 647 or traditional
 648 .Bx
 649 prototype and be pointed to by
 650 the
 651 .Va sa_handler
 652 member of
 653 .Vt "struct sigaction" .
 654 In practice,
 655 .Fx
 656 always sends the three arguments of the latter and since the
 657 .Tn ANSI C
 658 prototype is a subset, both will work.
 659 The
 660 .Va sa_handler
 661 member declaration in
 662 .Fx
 663 include files is that of
 664 .Tn ANSI C
 665 (as required by
 666 .Tn POSIX ) ,
 667 so a function pointer of a
 668 .Bx Ns -style
 669 function needs to be casted to
 670 compile without warning.
 671 The traditional
 672 .Bx
 673 style is not portable and since its capabilities
 674 are a full subset of a
 675 .Dv SA_SIGINFO
 676 handler,
 677 its use is deprecated.
 678 .Pp
 679 The
 680 .Fa sig
 681 argument is the signal number, one of the
 682 .Dv SIG...
 683 values from
 684 .In signal.h .
 685 .Pp
 686 The
 687 .Fa code
 688 argument of the
 689 .Bx Ns -style
 690 handler and the
 691 .Va si_code
 692 member of the
 693 .Fa info
 694 argument to a
 695 .Dv SA_SIGINFO
 696 handler contain a numeric code explaining the
 697 cause of the signal, usually one of the
 698 .Dv SI_...
 699 values from
 700 .In sys/signal.h
 701 or codes specific to a signal, i.e., one of the
 702 .Dv FPE_...
 703 values for
 704 .Dv SIGFPE .
 705 .Pp
 706 The
 707 .Fa scp
 708 argument to a
 709 .Bx Ns -style
 710 handler points to an instance of
 711 .Vt "struct sigcontext" .
 712 .Pp
 713 The
 714 .Fa uap
 715 argument to a
 716 .Tn POSIX
 717 .Dv SA_SIGINFO
 718 handler points to an instance of
 719 ucontext_t.
 720 .Sh ERRORS
 721 The
 722 .Fn sigaction
 723 system call
 724 will fail and no new signal handler will be installed if one
 725 of the following occurs:
 726 .Bl -tag -width Er
 727 .It Bq Er EINVAL
 728 The
 729 .Fa sig
 730 argument
 731 is not a valid signal number.
 732 .It Bq Er EINVAL
 733 An attempt is made to ignore or supply a handler for
 734 .Dv SIGKILL
 735 or
 736 .Dv SIGSTOP .
 737 .El
 738 .Sh SEE ALSO
 739 .Xr kill 1 ,
 740 .Xr kill 2 ,
 741 .Xr ptrace 2 ,
 742 .Xr sigaltstack 2 ,
 743 .Xr sigpending 2 ,
 744 .Xr sigprocmask 2 ,
 745 .Xr sigsuspend 2 ,
 746 .Xr wait 2 ,
 747 .Xr fpsetmask 3 ,
 748 .Xr setjmp 3 ,
 749 .Xr siginfo 3 ,
 750 .Xr siginterrupt 3 ,
 751 .Xr sigsetops 3 ,
 752 .Xr ucontext 3 ,
 753 .Xr tty 4
 754 .Sh STANDARDS
 755 The
 756 .Fn sigaction
 757 system call is expected to conform to
 758 .St -p1003.1-90 .
 759 The
 760 .Dv SA_ONSTACK
 761 and
 762 .Dv SA_RESTART
 763 flags are Berkeley extensions,
 764 as are the signals,
 765 .Dv SIGTRAP ,
 766 .Dv SIGEMT ,
 767 .Dv SIGBUS ,
 768 .Dv SIGSYS ,
 769 .Dv SIGURG ,
 770 .Dv SIGIO ,
 771 .Dv SIGXCPU ,
 772 .Dv SIGXFSZ ,
 773 .Dv SIGVTALRM ,
 774 .Dv SIGPROF ,
 775 .Dv SIGWINCH ,
 776 and
 777 .Dv SIGINFO .
 778 Those signals are available on most
 779 .Bx Ns \-derived
 780 systems.
 781 The
 782 .Dv SA_NODEFER
 783 and
 784 .Dv SA_RESETHAND
 785 flags are intended for backwards compatibility with other operating
 786 systems.
 787 The
 788 .Dv SA_NOCLDSTOP ,
 789 and
 790 .Dv SA_NOCLDWAIT
 791 .\" and
 792 .\" SA_SIGINFO
 793 flags are featuring options commonly found in other operating systems.
 794 The flags are approved by
 795 .St -susv2 ,
 796 along with the option to avoid zombie creation by ignoring
 797 .Dv SIGCHLD .