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 .\" 3. All advertising materials mentioning features or use of this software
  13 .\"    must display the following acknowledgement:
  14 .\"     This product includes software developed by the University of
  15 .\"     California, Berkeley and its contributors.
  16 .\" 4. Neither the name of the University nor the names of its contributors
  17 .\"    may be used to endorse or promote products derived from this software
  18 .\"    without specific prior written permission.
  19 .\"
  20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  23 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  30 .\" SUCH DAMAGE.
  31 .\"
  32 .\"     From: @(#)sigaction.2   8.2 (Berkeley) 4/3/94
  33 .\" $FreeBSD: src/lib/libc/sys/sigaction.2,v 1.22.2.10 2002/12/29 16:35:34 schweikh Exp $
  34 .\"
  35 .Dd April 3, 1994
  36 .Dt SIGACTION 2
  37 .Os
  38 .Sh NAME
  39 .Nm sigaction
  40 .Nd software signal facilities
  41 .Sh LIBRARY
  42 .Lb libc
  43 .Sh SYNOPSIS
  44 .In signal.h
  45 .Bd -literal
  46 struct sigaction {
  47         /*
  48          * Signal handler function if flag SA_SIGINFO is not used and for
  49          * SIG_DFL and SIG_IGN.
  50          */
  51         void     (*sa_handler)(int);
  52
  53         /* Signal handler function if flag SA_SIGINFO is used */
  54         void     (*sa_sigaction)(int, siginfo_t *, void *);
  55
  56         sigset_t sa_mask;            /* signal mask to apply */
  57         int      sa_flags;           /* see signal options below */
  58 };
  59 .Ed
  60 .Ft int
  61 .Fn sigaction "int sig" "const struct sigaction *act" "struct sigaction *oact"
  62 .Sh DESCRIPTION
  63 The system defines a set of signals that may be delivered to a process.
  64 Signal delivery resembles the occurrence of a hardware interrupt:
  65 the signal is normally blocked from further occurrence, the current process
  66 context is saved, and a new one is built.
  67 A process may specify a
  68 .Em handler
  69 to which a signal is delivered, or specify that a signal is to be
  70 .Em ignored .
  71 A process may also specify that a default action is to be taken
  72 by the system when a signal occurs.
  73 A signal may also be
  74 .Em blocked ,
  75 in which case its delivery is postponed until it is
  76 .Em unblocked .
  77 The action to be taken on delivery is determined at the time
  78 of delivery.
  79 Normally, signal handlers execute on the current stack
  80 of the process.
  81 This may be changed, on a per-handler basis,
  82 so that signals are taken on a special
  83 .Em "signal stack" .
  84 .Pp
  85 Signal routines normally execute with the signal that caused their
  86 invocation
  87 .Em blocked ,
  88 but other signals may yet occur.
  89 A global
  90 .Em "signal mask"
  91 defines the set of signals currently blocked from delivery
  92 to a process.
  93 The signal mask for a process is initialized
  94 from that of its parent (normally empty).
  95 It may be changed with a
  96 .Xr sigprocmask 2
  97 call, or when a signal is delivered to the process.
  98 .Pp
  99 When a signal
 100 condition arises for a process, the signal is added to a set of
 101 signals pending for the process.
 102 If the signal is not currently
 103 .Em blocked
 104 by the process then it is delivered to the process.
 105 Signals may be delivered any time a process enters the operating system
 106 (e.g., during a system call, page fault or trap, or clock interrupt).
 107 If multiple signals are ready to be delivered at the same time,
 108 any signals that could be caused by traps are delivered first.
 109 Additional signals may be processed at the same time, with each
 110 appearing to interrupt the handlers for the previous signals
 111 before their first instructions.
 112 The set of pending signals is returned by the
 113 .Xr sigpending 2
 114 function.
 115 When a caught signal
 116 is delivered, the current state of the process is saved,
 117 a new signal mask is calculated (as described below),
 118 and the signal handler is invoked.
 119 The call to the handler
 120 is arranged so that if the signal handling routine returns
 121 normally the process will resume execution in the context
 122 from before the signal's delivery.
 123 If the process wishes to resume in a different context, then it
 124 must arrange to restore the previous context itself.
 125 .Pp
 126 When a signal is delivered to a process a new signal mask is
 127 installed for the duration of the process' signal handler
 128 (or until a
 129 .Xr sigprocmask 2
 130 call is made).
 131 This mask is formed by taking the union of the current signal mask set,
 132 the signal to be delivered, and
 133 the signal mask associated with the handler to be invoked.
 134 .Pp
 135 .Fn Sigaction
 136 assigns an action for a signal specified by
 137 .Fa sig .
 138 If
 139 .Fa act
 140 is non-zero, it
 141 specifies an action
 142 .Pf ( Dv SIG_DFL ,
 143 .Dv SIG_IGN ,
 144 or a handler routine) and mask
 145 to be used when delivering the specified signal.
 146 If
 147 .Fa oact
 148 is non-zero, the previous handling information for the signal
 149 is returned to the user.
 150 .Pp
 151 Once a signal handler is installed, it normally remains installed
 152 until another
 153 .Fn sigaction
 154 call is made, or an
 155 .Xr execve 2
 156 is performed.
 157 A signal-specific default action may be reset by
 158 setting
 159 .Fa sa_handler
 160 to
 161 .Dv SIG_DFL .
 162 The defaults are process termination, possibly with core dump;
 163 no action; stopping the process; or continuing the process.
 164 See the signal list below for each signal's default action.
 165 If
 166 .Fa sa_handler
 167 is
 168 .Dv SIG_DFL ,
 169 the default action for the signal is to discard the signal,
 170 and if a signal is pending,
 171 the pending signal is discarded even if the signal is masked.
 172 If
 173 .Fa sa_handler
 174 is set to
 175 .Dv SIG_IGN
 176 current and pending instances
 177 of the signal are ignored and discarded.
 178 .Pp
 179 Options may be specified by setting
 180 .Em sa_flags .
 181 The meaning of the various bits is as follows:
 182 .Bl -tag -offset indent -width SA_RESETHANDXX
 183 .It Dv SA_NOCLDSTOP
 184 If this bit is set when installing a catching function
 185 for the
 186 .Dv SIGCHLD
 187 signal,
 188 the
 189 .Dv SIGCHLD
 190 signal will be generated only when a child process exits,
 191 not when a child process stops.
 192 .It Dv SA_NOCLDWAIT
 193 If this bit is set when calling
 194 .Fn sigaction
 195 for the
 196 .Dv SIGCHLD
 197 signal, the system will not create zombie processes when children of
 198 the calling process exit.
 199 If the calling process subsequently issues a
 200 .Xr wait 2
 201 (or equivalent), it blocks until all of the calling process's child
 202 processes terminate, and then returns a value of -1 with
 203 .Va errno
 204 set to
 205 .Er ECHILD .
 206 .It Dv SA_ONSTACK
 207 If this bit is set, the system will deliver the signal to the process
 208 on a
 209 .Em "signal stack" ,
 210 specified with
 211 .Xr sigaltstack 2 .
 212 .It Dv SA_NODEFER
 213 If this bit is set, further occurrences of the delivered signal are
 214 not masked during the execution of the handler.
 215 .It Dv SA_RESETHAND
 216 If this bit is set, the handler is reset back to
 217 .Dv SIG_DFL
 218 at the moment the signal is delivered.
 219 .It Dv SA_SIGINFO
 220 If this bit is set, the handler function is assumed to be pointed to by the
 221 .Dv sa_sigaction
 222 member of struct sigaction and should match the prototype shown above or as
 223 below in
 224 .Sx EXAMPLES .
 225 This bit should not be set when assigning
 226 .Dv SIG_DFL
 227 or
 228 .Dv SIG_IGN .
 229 .El
 230 .Pp
 231 If a signal is caught during the system calls listed below,
 232 the call may be forced to terminate
 233 with the error
 234 .Er EINTR ,
 235 the call may return with a data transfer shorter than requested,
 236 or the call may be restarted.
 237 Restart of pending calls is requested
 238 by setting the
 239 .Dv SA_RESTART
 240 bit in
 241 .Ar sa_flags .
 242 The affected system calls include
 243 .Xr open 2 ,
 244 .Xr read 2 ,
 245 .Xr write 2 ,
 246 .Xr sendto 2 ,
 247 .Xr recvfrom 2 ,
 248 .Xr sendmsg 2
 249 and
 250 .Xr recvmsg 2
 251 on a communications channel or a slow device (such as a terminal,
 252 but not a regular file)
 253 and during a
 254 .Xr wait 2
 255 or
 256 .Xr ioctl 2 .
 257 However, calls that have already committed are not restarted,
 258 but instead return a partial success (for example, a short read count).
 259 .Pp
 260 After a
 261 .Xr fork 2
 262 or
 263 .Xr vfork 2
 264 all signals, the signal mask, the signal stack,
 265 and the restart/interrupt flags are inherited by the child.
 266 .Pp
 267 .Xr Execve 2
 268 reinstates the default
 269 action for all signals which were caught and
 270 resets all signals to be caught on the user stack.
 271 Ignored signals remain ignored;
 272 the signal mask remains the same;
 273 signals that restart pending system calls continue to do so.
 274 .Pp
 275 The following is a list of all signals
 276 with names as in the include file
 277 .In signal.h :
 278 .Bl -column SIGVTALARMXX "create core imagexxx"
 279 .It Sy "NAME    Default Action  Description"
 280 .It Dv SIGHUP No "      terminate process" "    terminal line hangup"
 281 .It Dv SIGINT No "      terminate process" "    interrupt program"
 282 .It Dv SIGQUIT No "     create core image" "    quit program"
 283 .It Dv SIGILL No "      create core image" "    illegal instruction"
 284 .It Dv SIGTRAP No "     create core image" "    trace trap"
 285 .It Dv SIGABRT No "     create core image" Ta Xr abort 3
 286 call (formerly
 287 .Dv SIGIOT )
 288 .It Dv SIGEMT No "      create core image" "    emulate instruction executed"
 289 .It Dv SIGFPE No "      create core image" "    floating-point exception"
 290 .It Dv SIGKILL No "     terminate process" "    kill program"
 291 .It Dv SIGBUS No "      create core image" "    bus error"
 292 .It Dv SIGSEGV No "     create core image" "    segmentation violation"
 293 .It Dv SIGSYS No "      create core image" "    non-existent system call invoked"
 294 .It Dv SIGPIPE No "     terminate process" "    write on a pipe with no reader"
 295 .It Dv SIGALRM No "     terminate process" "    real-time timer expired"
 296 .It Dv SIGTERM No "     terminate process" "    software termination signal"
 297 .It Dv SIGURG No "      discard signal" "       urgent condition present on socket"
 298 .It Dv SIGSTOP No "     stop process" " stop (cannot be caught or ignored)"
 299 .It Dv SIGTSTP No "     stop process" " stop signal generated from keyboard"
 300 .It Dv SIGCONT No "     discard signal" "       continue after stop"
 301 .It Dv SIGCHLD No "     discard signal" "       child status has changed"
 302 .It Dv SIGTTIN No "     stop process" " background read attempted from control terminal"
 303 .It Dv SIGTTOU No "     stop process" " background write attempted to control terminal"
 304 .It Dv SIGIO No "       discard signal" Tn "    I/O"
 305 is possible on a descriptor (see
 306 .Xr fcntl 2 )
 307 .It Dv SIGXCPU No "     terminate process" "    cpu time limit exceeded (see"
 308 .Xr setrlimit 2 )
 309 .It Dv SIGXFSZ No "     terminate process" "    file size limit exceeded (see"
 310 .Xr setrlimit 2 )
 311 .It Dv SIGVTALRM No "   terminate process" "    virtual time alarm (see"
 312 .Xr setitimer 2 )
 313 .It Dv SIGPROF No "     terminate process" "    profiling timer alarm (see"
 314 .Xr setitimer 2 )
 315 .It Dv SIGWINCH No "    discard signal" "       Window size change"
 316 .It Dv SIGINFO No "     discard signal" "       status request from keyboard"
 317 .It Dv SIGUSR1 No "     terminate process" "    User defined signal 1"
 318 .It Dv SIGUSR2 No "     terminate process" "    User defined signal 2"
 319 .El
 320 .Sh NOTE
 321 The
 322 .Fa sa_mask
 323 field specified in
 324 .Fa act
 325 is not allowed to block
 326 .Dv SIGKILL
 327 or
 328 .Dv SIGSTOP .
 329 Any attempt to do so will be silently ignored.
 330 .Pp
 331 The following functions are either reentrant or not interruptible
 332 by signals and are async-signal safe.
 333 Therefore applications may
 334 invoke them, without restriction, from signal-catching functions:
 335 .Pp
 336 Base Interfaces:
 337 .Pp
 338 .Fn _exit ,
 339 .Fn access ,
 340 .Fn alarm ,
 341 .Fn cfgetispeed ,
 342 .Fn cfgetospeed ,
 343 .Fn cfsetispeed ,
 344 .Fn cfsetospeed ,
 345 .Fn chdir ,
 346 .Fn chmod ,
 347 .Fn chown ,
 348 .Fn close ,
 349 .Fn creat ,
 350 .Fn dup ,
 351 .Fn dup2 ,
 352 .Fn execle ,
 353 .Fn execve ,
 354 .Fn fcntl ,
 355 .Fn fork ,
 356 .Fn fpathconf ,
 357 .Fn fstat ,
 358 .Fn fsync ,
 359 .Fn getegid ,
 360 .Fn geteuid ,
 361 .Fn getgid ,
 362 .Fn getgroups ,
 363 .Fn getpgrp ,
 364 .Fn getpid ,
 365 .Fn getppid ,
 366 .Fn getuid ,
 367 .Fn kill ,
 368 .Fn link ,
 369 .Fn lseek ,
 370 .Fn mkdir ,
 371 .Fn mkfifo ,
 372 .Fn open ,
 373 .Fn pathconf ,
 374 .Fn pause ,
 375 .Fn pipe ,
 376 .Fn raise ,
 377 .Fn read ,
 378 .Fn rename ,
 379 .Fn rmdir ,
 380 .Fn setgid ,
 381 .Fn setpgid ,
 382 .Fn setsid ,
 383 .Fn setuid ,
 384 .Fn sigaction ,
 385 .Fn sigaddset ,
 386 .Fn sigdelset ,
 387 .Fn sigemptyset ,
 388 .Fn sigfillset  ,
 389 .Fn sigismember ,
 390 .Fn signal ,
 391 .Fn sigpending ,
 392 .Fn sigprocmask ,
 393 .Fn sigsuspend ,
 394 .Fn sleep ,
 395 .Fn stat ,
 396 .Fn sysconf ,
 397 .Fn tcdrain ,
 398 .Fn tcflow ,
 399 .Fn tcflush ,
 400 .Fn tcgetattr ,
 401 .Fn tcgetpgrp ,
 402 .Fn tcsendbreak ,
 403 .Fn tcsetattr ,
 404 .Fn tcsetpgrp ,
 405 .Fn time ,
 406 .Fn times ,
 407 .Fn umask ,
 408 .Fn uname ,
 409 .Fn unlink ,
 410 .Fn utime ,
 411 .Fn wait ,
 412 .Fn waitpid ,
 413 .Fn write .
 414 .Pp
 415 Realtime Interfaces:
 416 .Pp
 417 .Fn aio_error ,
 418 .Fn clock_gettime ,
 419 .Fn sigpause ,
 420 .\".Fn timer_getoverrun ,
 421 .Fn aio_return ,
 422 .\".Fn fdatasync ,
 423 .Fn sigqueue ,
 424 .\".Fn timer_gettime ,
 425 .Fn aio_suspend ,
 426 .Fn sem_post ,
 427 .Fn sigset .
 428 .\".Fn timer_settime .
 429 .Pp
 430 All functions not in the above lists are considered to be unsafe
 431 with respect to signals.
 432 That is to say, the behaviour of such
 433 functions when called from a signal handler is undefined.
 434 .Sh RETURN VALUES
 435 .Rv -std sigaction
 436 .Sh EXAMPLES
 437 There are three possible prototypes the handler may match:
 438 .Bl -tag -offset indent -width short
 439 .It ANSI C:
 440 .Ft void
 441 .Fn handler int ;
 442 .It Traditional BSD style:
 443 .Ft void
 444 .Fn handler int "int code" "struct sigcontext *scp" ;
 445 .It POSIX SA_SIGINFO:
 446 .Ft void
 447 .Fn handler int "siginfo_t *info" "ucontext_t *uap" ;
 448 .El
 449 .Pp
 450 The handler function should match the
 451 .Dv SA_SIGINFO
 452 prototype if the
 453 .Dv SA_SIGINFO
 454 bit is set in flags.
 455 It then should be pointed to by the
 456 .Dv sa_sigaction
 457 member of
 458 .Dv struct sigaction .
 459 Note that you should not assign
 460 .Dv SIG_DFL
 461 or
 462 .Dv SIG_IGN
 463 this way.
 464 .Pp
 465 If the
 466 .Dv SA_SIGINFO
 467 flag is not set, the handler function should match
 468 either the ANSI C or traditional
 469 .Bx
 470 prototype and be pointed to by
 471 the
 472 .Dv sa_handler
 473 member of
 474 .Dv struct sigaction .
 475 In practice,
 476 .Dx
 477 always sends the three arguments of the latter and since the ANSI C
 478 prototype is a subset, both will work.
 479 The
 480 .Dv sa_handler
 481 member declaration in
 482 .Dx
 483 include files is that of ANSI C (as required by POSIX),
 484 so a function pointer of a
 485 .Bx Ns -style
 486 function needs to be casted to
 487 compile without warning.
 488 The traditional
 489 .Bx
 490 style is not portable and since its capabilities are a full subset of a
 491 .Dv SA_SIGINFO
 492 handler, its use is deprecated.
 493 .Pp
 494 The
 495 .Fa sig
 496 argument is the signal number, one of the
 497 .Dv SIG...
 498 .In signal.h .
 499 .Pp
 500 The
 501 .Fa code
 502 argument of the
 503 .Bx Ns -style
 504 handler and the
 505 .Dv si_code
 506 member of the
 507 .Dv info
 508 argument to a
 509 .Dv SA_SIGINFO
 510 handler contain a numeric code explaining the
 511 cause of the signal, usually one of the
 512 .Dv SI_...
 513 values from
 514 .In sys/signal.h
 515 or codes specific to a signal, i.e.\& one of the
 516 .Dv FPE_...
 517 values for
 518 .Dv SIGFPE .
 519 .Pp
 520 The
 521 .Fa scp
 522 argument to a
 523 .Bx Ns -style
 524 handler points to an instance of struct
 525 sigcontext.
 526 .Pp
 527 The
 528 .Fa uap
 529 argument to a POSIX
 530 .Dv SA_SIGINFO
 531 handler points to an instance of ucontext_t.
 532 .Sh ERRORS
 533 .Fn Sigaction
 534 will fail and no new signal handler will be installed if one
 535 of the following occurs:
 536 .Bl -tag -width Er
 537 .It Bq Er EFAULT
 538 Either
 539 .Fa act
 540 or
 541 .Fa oact
 542 points to memory that is not a valid part of the process
 543 address space.
 544 .It Bq Er EINVAL
 545 .Fa Sig
 546 is not a valid signal number.
 547 .It Bq Er EINVAL
 548 An attempt is made to ignore or supply a handler for
 549 .Dv SIGKILL
 550 or
 551 .Dv SIGSTOP .
 552 .El
 553 .Sh SEE ALSO
 554 .Xr kill 1 ,
 555 .Xr kill 2 ,
 556 .Xr ptrace 2 ,
 557 .Xr sigaltstack 2 ,
 558 .Xr sigpending 2 ,
 559 .Xr sigprocmask 2 ,
 560 .Xr sigsuspend 2 ,
 561 .Xr wait 2 ,
 562 .Xr fpsetmask 3 ,
 563 .Xr setjmp 3 ,
 564 .Xr siginterrupt 3 ,
 565 .Xr sigsetops 3 ,
 566 .Xr ucontext 3 ,
 567 .Xr tty 4
 568 .Sh STANDARDS
 569 The
 570 .Fn sigaction
 571 function call is expected to conform to
 572 .St -p1003.1-90 .
 573 The
 574 .Dv SA_ONSTACK
 575 and
 576 .Dv SA_RESTART
 577 flags are Berkeley extensions,
 578 as are the signals,
 579 .Dv SIGTRAP ,
 580 .Dv SIGEMT ,
 581 .Dv SIGBUS ,
 582 .Dv SIGSYS ,
 583 .Dv SIGURG ,
 584 .Dv SIGIO ,
 585 .Dv SIGXCPU ,
 586 .Dv SIGXFSZ ,
 587 .Dv SIGVTALRM ,
 588 .Dv SIGPROF ,
 589 .Dv SIGWINCH ,
 590 and
 591 .Dv SIGINFO .
 592 Those signals are available on most
 593 .Bx Ns \-derived
 594 systems.
 595 The
 596 .Dv SA_NODEFER
 597 and
 598 .Dv SA_RESETHAND
 599 flags are intended for backwards compatibility with other operating
 600 systems.
 601 The
 602 .Dv SA_NOCLDSTOP ,
 603 and
 604 .Dv SA_NOCLDWAIT
 605 .\" and
 606 .\" SA_SIGINFO
 607 flags are featuring options commonly found in other operating systems.