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